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

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

@@ -9,22 +9,30 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+exports.addedUndeclaredControlsOf = exports.partsCompletenessOf = exports.completenessOf = exports.inventoryIdsOf = exports.seePart = exports.seeFrame = exports.PLAIN_CONTROL_SELECTOR = exports.SDK_CONTROLS = exports.isMissingStateGap = exports.completenessGapLineOf = exports.completenessGapsOf = exports.findingKeyOf = exports.isFindingOf = exports.smallChangeHintsOf = exports.introducedControlStateGapsOf = 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");
+const vite_cache_1 = require("../vite-cache");
 const serve_1 = require("../serve");
 const shot_1 = require("../shot");
 const thumb_1 = require("../thumb");
+const run_yield_1 = require("../run-yield");
+const actions_1 = require("./actions");
 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 render_check_1 = require("./render-check");
 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 demo_backdrop_1 = require("./demo-backdrop");
+const code_hash_1 = require("../code-hash");
+const compare_cache_1 = require("./compare-cache");
+const served_cache_1 = require("./served-cache");
 const KINDS = {
     disclosure: { surface: 'body', closed: 'collapsed' },
     button: { adds: ['active'] },
@@ -54,7 +62,7 @@ const requiredInteractionsOf = (control) => {
     ];
 };
 const gridGapOf = (options) => {
-    const { grid, states, interactions } = options;
+    const { grid, states, interactions, disabledStates = new Set() } = options;
     const fix = `draw its states with interactionRows, which gives the grid a column per interaction (${interactions.join(', ')})`;
     if (!isRecord(grid) || !Array.isArray(grid['columns']) || !isRecord(grid['rows']))
         return `the part has no grid - ${fix}`;
@@ -62,12 +70,14 @@ const gridGapOf = (options) => {
     const missing = interactions.filter((interaction) => !columns.includes(interaction));
     if (missing.length > 0)
         return `its grid has no column ${missing.join(', ')} - ${fix}`;
-    const holes = Object.entries(grid['rows']).flatMap(([row, cells]) => interactions
-        .filter((interaction) => {
-        const state = isRecord(cells) ? cells[interaction] : undefined;
-        return typeof state !== 'string' || !states.includes(state);
-    })
-        .map((interaction) => `${row} ${interaction}`));
+    const holes = Object.entries(grid['rows']).flatMap(([row, cells]) => isRecord(cells) && typeof cells['rest'] === 'string' && disabledStates.has(cells['rest'])
+        ? []
+        : interactions
+            .filter((interaction) => {
+            const state = isRecord(cells) ? cells[interaction] : undefined;
+            return typeof state !== 'string' || !states.includes(state);
+        })
+            .map((interaction) => `${row} ${interaction}`));
     return holes.length > 0 ? `its grid draws no state in ${holes.join(', ')} - ${fix}` : null;
 };
 const declaredControlsOf = (value) => isRecord(value)
@@ -147,6 +157,18 @@ const controlStateGapsOf = (options) => {
     }));
 };
 exports.controlStateGapsOf = controlStateGapsOf;
+/**
+ * The `CONTROL-STATE` gaps render check fails a part on. Only a sketch variant fails, and only on interaction states
+ * its base part, `base`, does not already draw as a gap: product check leaves those gaps to `design complete`.
+ */
+const introducedControlStateGapsOf = (options) => {
+    const { part, controls, states, sketch, base } = options;
+    if (!sketch)
+        return [];
+    const inherited = new Set(base && !(0, exports.isControlPart)({ part, controls: base.controls }) ? base.states.filter(exports.isInteractionState) : []);
+    return (0, exports.controlStateGapsOf)({ part, controls, states: states.filter((state) => !inherited.has(state)) });
+};
+exports.introducedControlStateGapsOf = introducedControlStateGapsOf;
 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
@@ -166,7 +188,7 @@ const isFindingOf = (declared) => (found) => {
         !(found.kind === 'control' && found.marked !== null);
 };
 exports.isFindingOf = isFindingOf;
-const findingKeyOf = (found) => `${found.kind} ${found.what} ${found.path}`;
+const findingKeyOf = (found) => { var _a; return `${found.kind} ${found.what} ${found.path} ${(_a = found.label) !== null && _a !== void 0 ? _a : ''}`; };
 exports.findingKeyOf = findingKeyOf;
 const NATIVE_CONTROLS = ['button', 'a[href]', 'input:not([type="hidden"])', 'select', 'textarea', 'summary'];
 const discoveryGapsOf = (options) => {
@@ -207,6 +229,28 @@ const discoveryGapsOf = (options) => {
             };
     });
 };
+const actionGapsOf = (options) => {
+    var _a, _b, _c;
+    const { part, declared, frames } = options;
+    const groups = new Map();
+    for (const frame of frames.filter((seen) => seen.interaction === null))
+        for (const found of (_a = frame.found) !== null && _a !== void 0 ? _a : []) {
+            if (found.action !== null ||
+                ((_b = found.owner) !== null && _b !== void 0 ? _b : 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; }))
+                continue;
+            const key = (0, exports.findingKeyOf)(found);
+            const group = (_c = groups.get(key)) !== null && _c !== void 0 ? _c : { found, states: [] };
+            if (!group.states.includes(frame.state))
+                group.states.push(frame.state);
+            groups.set(key, group);
+        }
+    return [...groups.values()].map(({ found, states }) => ({
+        code: 'ACTION-UNDECLARED',
+        target: part,
+        detail: `${found.what}${found.label ? ` "${found.label}"` : ''} at ${found.path} in ${statesShownOf(states)} - declare what it does: data-et-action="<state>" or "emit:<output>"`,
+    }));
+};
 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) => {
@@ -499,7 +543,10 @@ const completenessGapsOf = (options) => {
                 detail: `${control.part} is not design complete: ${used.length} gap(s) - run design complete ${control.part}`,
             });
         const interactions = control.part === null && !part.startsWith('pages/') ? requiredInteractionsOf(control) : [];
-        const gridGap = interactions.length > 0 ? gridGapOf({ grid, states, interactions }) : null;
+        const disabledStates = new Set(frames
+            .filter((frame) => frame.interaction === null && frame.controls.some((seen) => seen.id === id && seen.disabled))
+            .map((frame) => frame.state));
+        const gridGap = interactions.length > 0 ? gridGapOf({ grid, states, interactions, disabledStates }) : null;
         if (gridGap)
             gaps.push({ code: 'CONTROL-GRID-MISSING', target: `${part}.${id}`, detail: gridGap });
         if (!seenIds.has(id)) {
@@ -517,6 +564,7 @@ const completenessGapsOf = (options) => {
     return [
         ...gaps,
         ...discoveryGapsOf({ part, declared, frames }).filter((gap) => !isUndeclaredControlGap(gap)),
+        ...actionGapsOf({ part, declared, frames }),
         ...ownerGapsOf({ part, declared, frames, referenced }),
         ...overrideGapsOf({ part, frames }),
         ...inventoryGapsOf({ part, inventory }),
@@ -647,7 +695,7 @@ exports.SDK_CONTROLS = [
     'et-accordion',
     'et-cascader',
     'et-checkbox',
-    'et-chip',
+    'et-chip:is([data-removable], [role])',
     'et-color-input',
     'et-counter',
     'et-date-input',
@@ -682,10 +730,11 @@ 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(', ');
+const DIALOG_ROLES = ['dialog', 'alertdialog'];
+const FOCUS_CONTAINER = [
+    ...COMPOSITE_ROLES.flatMap((role) => [`[role="${role}"][tabindex="-1"]`, `[role="${role}"][aria-activedescendant]`]),
+    ...DIALOG_ROLES.map((role) => `[role="${role}"][tabindex="-1"]`),
+].join(', ');
 exports.PLAIN_CONTROL_SELECTOR = `:is(${PLAIN_CONTROLS.join(', ')}):not(${FOCUS_CONTAINER})`;
 const discoverControls = `((root) => {
   const LIKELY = ${JSON.stringify(LIKELY_CONTROLS)};
@@ -695,7 +744,7 @@ const discoverControls = `((root) => {
   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;
+  const FORCED_HOVER = /:is\\(:hover,\\s*\\[data-et-force~="?hover"?\\](?:,\\s*\\[data-et-force~="?active"?\\])?\\)/g;
   const hoveredOf = (written) => {
     const selector = written.replace(FORCED_HOVER, ':hover');
     const match = new RegExp(HOVER.source).exec(selector);
@@ -756,6 +805,8 @@ const discoverControls = `((root) => {
     }
     return null;
   };
+  const labelOf = (element) =>
+    (element.getAttribute('aria-label') ?? element.innerText ?? element.textContent ?? '').replace(/\\s+/g, ' ').trim().slice(0, 60) || null;
   const found = [];
   for (const element of root.querySelectorAll('*')) {
     if (!rendered(element)) continue;
@@ -763,7 +814,7 @@ const discoverControls = `((root) => {
     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), owner: ownerOf(element)?.key ?? null, box: frameBoxOf(element) });
+      found.push({ kind: 'control', what: what.startsWith('[') ? element.tagName.toLowerCase() + what : what, path: pathOf(element), label: labelOf(element), marked: markedOf(element), within: withinOf(element), owner: ownerOf(element)?.key ?? null, box: frameBoxOf(element), covered: isCovered(element), ...(element.matches(${JSON.stringify(actions_1.INTERACTIVE_SELECTOR)}) ? { action: element.getAttribute('data-et-action') } : {}) });
       continue;
     }
     const cursor = getComputedStyle(element).cursor;
@@ -773,7 +824,7 @@ const discoverControls = `((root) => {
     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) });
+    found.push({ kind: 'unclassified', what: nameOf(element) + ' with ' + reason, path: pathOf(element), label: labelOf(element), marked: null, within: [], owner: ownerOf(element)?.key ?? null, box: frameBoxOf(element), covered: isCovered(element) });
   }
   return found;
 })`;
@@ -857,7 +908,31 @@ const seeFrame = (options) => `(() => {
       ? { 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 isCovered = (element) => {
+    const box = element.getBoundingClientRect();
+    if (box.width <= 0 || box.height <= 0) return false;
+    const x = [box.left + 1, box.left + box.width / 2, box.right - 1];
+    const y = [box.top + 1, box.top + box.height / 2, box.bottom - 1];
+    const points = [[x[1], y[1]], [x[0], y[0]], [x[2], y[0]], [x[0], y[2]], [x[2], y[2]]];
+    let hit = false;
+    const inline = element.style.getPropertyValue('pointer-events');
+    const priority = element.style.getPropertyPriority('pointer-events');
+    element.style.setProperty('pointer-events', 'auto', 'important');
+    try {
+      for (const [px, py] of points) {
+        const top = document.elementFromPoint(px, py);
+        if (top === null) return false;
+        if (element.contains(top)) return false;
+        hit = true;
+      }
+    } finally {
+      if (inline) element.style.setProperty('pointer-events', inline, priority);
+      else element.style.removeProperty('pointer-events');
+    }
+    return hit;
+  };
   const OWN = ${JSON.stringify(options.part)};
+  const CONTROL_PARTS = ${JSON.stringify(options.controlParts)};
   const tokensOf = (element, name) => (element.getAttribute(name) ?? '').split(' ').filter(Boolean);
   const ownerOf = (element) => {
     const slotted = tokensOf(element, 'data-et-slot');
@@ -936,15 +1011,21 @@ const seeFrame = (options) => `(() => {
     const box = element.getBoundingClientRect();
     const x = Math.max(0, box.x + scrollX - ${PAD});
     const y = Math.max(0, box.y + scrollY - ${PAD});
+    const width = Math.min(box.x + scrollX + box.width + ${PAD}, document.documentElement.scrollWidth) - x;
+    const height = Math.min(box.y + scrollY + box.height + ${PAD}, document.documentElement.scrollHeight) - y;
     return {
       at,
       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,
+      box: box.width > 0 && box.height > 0 && width > 0 && height > 0 ? { x, y, width, height } : null,
       selected: isSelected(element),
       look: lookOf(element),
     };
   };
-  const controls = [...root.querySelectorAll('[data-et-control]')].filter((element) => ownerOf(element) === null).map((element) => {
+  const isOwnControl = (element) => {
+    const owner = ownerOf(element);
+    return owner === null || CONTROL_PARTS[element.getAttribute('data-et-control')] === owner.key;
+  };
+  const controls = [...root.querySelectorAll('[data-et-control]')].filter(isOwnControl).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(' '));
@@ -953,10 +1034,12 @@ const seeFrame = (options) => `(() => {
       disabled: parts.some(isDisabled),
       keyboard: parts.some(isKeyboard),
       frameBox: frameBoxOf(element),
+      covered: isCovered(element),
       ...tagged(element),
     };
   });
-  const surfaces = [...root.querySelectorAll('[data-et-surface]')].filter((element) => ownerOf(element) === null).map((element) => ({
+  const partRoot = [root, ...root.querySelectorAll('[data-et-part]')].find((element) => (element.getAttribute('data-et-part') ?? '').split(' ').includes(${JSON.stringify(options.part)}));
+  const surfaces = [...root.querySelectorAll('[data-et-surface]')].filter((element) => ownerOf(element) === null && !(element === partRoot && element.getAttribute('data-et-surface') === '')).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) })),
@@ -967,8 +1050,10 @@ const seeFrame = (options) => `(() => {
     surfaces,
     found: discover ? ${discoverControls}(root) : [],
     overrides: discover ? ${findOverrides}(${JSON.stringify(options.ownCss)}) : [],
+    backdrop: discover ? ${(0, demo_backdrop_1.findDemoBackdrop)(options.part)}(root) : null,
   };
 })()`;
+exports.seeFrame = seeFrame;
 const forceOn = ({ at, interaction, on, }) => `((at, interaction, on) => {
   const found = document.querySelector('[data-et-complete="' + at + '"]');
   for (const element of found.hasAttribute('data-et-control') ? ${controlPartsOf}(found) : [found]) {
@@ -981,22 +1066,26 @@ const forceOn = ({ at, interaction, on, }) => `((at, interaction, on) => {
 })(${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, part, ownCss } = options;
+    const { browser, base, frames, part, ownCss, controlParts, requested } = options;
     const context = yield browser.newContext();
     const seen = [];
     const refused = [];
     const shots = [];
+    if (requested)
+        (0, served_cache_1.recordRequests)(context, () => requested);
     try {
         const page = yield context.newPage();
-        for (const frame of frames) {
+        if (requested)
+            yield (yield context.newCDPSession(page)).send('Network.setCacheDisabled', { cacheDisabled: true });
+        const seeOne = (frame) => __awaiter(void 0, void 0, void 0, function* () {
             yield page.setViewportSize((0, shot_1.viewportOf)(frame.size));
             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({ discover: frame.interaction === null, part, ownCss, clip: frame.clip })));
+            yield (0, thumb_1.awaitSettled)(page);
+            const found = (yield page.evaluate((0, exports.seeFrame)({ discover: frame.interaction === null, part, ownCss, controlParts, clip: frame.clip })));
             if ('refused' in found) {
                 refused.push(`${frame.state}: ${found.refused}`);
-                continue;
+                return;
             }
             if (frame.interaction === null) {
                 const box = frame.clip ? yield page.locator('#root').boundingBox() : null;
@@ -1016,7 +1105,7 @@ const seeFrames = (options) => __awaiter(void 0, void 0, void 0, function* () {
                     const drawn = yield shot();
                     const drawnColours = (yield page.evaluate(colourSnapshot(element.at)));
                     yield page.evaluate(forceOn({ at: element.at, interaction, on: false }));
-                    yield page.evaluate(thumb_1.settled);
+                    yield (0, thumb_1.awaitSettled)(page);
                     const rest = yield shot();
                     const restColours = (yield page.evaluate(colourSnapshot(element.at)));
                     yield page.evaluate(forceOn({ at: element.at, interaction, on: true }));
@@ -1032,7 +1121,7 @@ const seeFrames = (options) => __awaiter(void 0, void 0, void 0, function* () {
             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 }));
+                controls.push(Object.assign(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 }), (control.covered ? { covered: true } : {})));
             for (const surface of found.surfaces) {
                 const options = [];
                 for (const option of surface.options)
@@ -1046,7 +1135,16 @@ const seeFrames = (options) => __awaiter(void 0, void 0, void 0, function* () {
                 surfaces,
                 found: found.found,
                 overrides: found.overrides,
+                backdrop: found.backdrop,
             });
+        });
+        for (const frame of frames) {
+            try {
+                yield seeOne(frame);
+            }
+            catch (error) {
+                refused.push(`${frame.state}: design check could not draw this frame (${error instanceof Error ? error.message.split('\n')[0] : String(error)})`);
+            }
         }
     }
     finally {
@@ -1067,13 +1165,20 @@ const seeFrames = (options) => __awaiter(void 0, void 0, void 0, function* () {
         }),
     };
 });
+const COMPLETENESS_SIGHTS = 'completeness-sights';
+const COMPLETENESS_SIGHTS_LIMIT = 64 * 1024 * 1024;
+const completenessCacheOf = (options) => ({
+    store: (0, served_cache_1.createServedCache)((0, vite_cache_1.viteCacheOf)(options.target, COMPLETENESS_SIGHTS), COMPLETENESS_SIGHTS_LIMIT),
+    served: (0, served_cache_1.createServedHashes)(options.base, (0, served_cache_1.fetchServedOf)((0, served_cache_1.reachableBaseOf)(options.address))),
+    salt: `${(0, code_hash_1.completenessCodeOf)()} ${(0, compare_cache_1.browserVersionOf)(options.from)}`,
+});
 /**
  * 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;
+    var _a, _b, _c, _d, _e, _f;
+    const { product, part, system, base, load, draw, restOnly = false, sketch = null, cache } = 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 }))
@@ -1118,7 +1223,17 @@ 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, changes } = yield draw((browser) => seeFrames({ browser, base, frames, part: key, ownCss }));
+    const controlParts = Object.fromEntries(Object.entries((_f = (0, exports.declaredControlsOf)(definition === null || definition === void 0 ? void 0 : definition.controls)) !== null && _f !== void 0 ? _f : {}).flatMap(([id, control]) => control.part === null ? [] : [[id, control.part]]));
+    const cacheKey = cache ? (0, compare_cache_1.cacheKeyOf)([cache.salt, product.name, sketch, key, frames, ownCss, controlParts]) : null;
+    const held = cache && cacheKey ? yield (0, served_cache_1.servedHitOf)(cache, cacheKey) : null;
+    const requested = [];
+    const drawn = () => __awaiter(void 0, void 0, void 0, function* () {
+        const sight = yield draw((browser) => seeFrames({ browser, base, frames, part: key, ownCss, controlParts, requested: cache ? requested : undefined }));
+        if (cache && cacheKey)
+            yield (0, served_cache_1.writeServed)(cache, { key: cacheKey, requested, value: sight });
+        return sight;
+    });
+    const { seen, refused, changes } = held !== null && held !== void 0 ? held : (yield drawn());
     const owner = (0, inventory_approval_1.partOwnerOf)({ product, part });
     return {
         definition,
@@ -1168,27 +1283,74 @@ const completenessOf = (options) => __awaiter(void 0, void 0, void 0, function*
     return Object.assign(Object.assign({ gaps }, (checked.exceptions.length > 0 ? { exceptions: checked.exceptions } : {})), (hints.length > 0 ? { hints } : {}));
 });
 exports.completenessOf = completenessOf;
+const slotsOf = (size) => {
+    let free = size;
+    const waiting = [];
+    return (work) => __awaiter(void 0, void 0, void 0, function* () {
+        if (free > 0)
+            free--;
+        else
+            yield new Promise((resolve) => waiting.push(resolve));
+        try {
+            return yield work();
+        }
+        finally {
+            const next = waiting.shift();
+            if (next)
+                next();
+            else
+                free++;
+        }
+    });
+};
 /**
  * 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 { target, config, product, sketch = null, warm } = 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)))
+    const chromium = yield resolveChromium(target);
+    if (!chromium)
         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 });
+    const queue = warm ? warm.queue() : (0, thumb_1.createDrawQueue)({ target, chromiumOf: resolveChromium });
+    const server = warm ? yield warm.server(config) : yield (0, serve_1.createDesignServer)({ target, config, listen: true, port: 0 });
+    const sights = new Map();
+    const atOnce = slotsOf(render_check_1.INSPECTS_AT_ONCE);
     try {
-        yield server.listen();
-        const { port } = (_d = server.httpServer) === null || _d === void 0 ? void 0 : _d.address();
+        if (!warm)
+            yield server.listen();
+        const address = (_d = server.httpServer) === null || _d === void 0 ? void 0 : _d.address();
+        const base = `http://localhost:${address.port}`;
+        const cache = options.cached ? completenessCacheOf({ target, base, address, from: chromium.from }) : undefined;
         const checked = new Map();
         const exceptions = [];
         const hints = new Map();
+        const sightOf = (resolved) => {
+            const key = (0, resolve_product_1.partKeyOf)(resolved);
+            const known = sights.get(key);
+            if (known)
+                return known;
+            const sight = atOnce(() => (0, exports.seePart)({
+                product,
+                part: resolved,
+                system,
+                base,
+                load: (id) => server.ssrLoadModule(id),
+                draw: (job) => queue.run(job),
+                sketch,
+                cache,
+                restOnly: options.undeclaredOnly,
+            }));
+            sight.catch(() => undefined);
+            sights.set(key, sight);
+            return sight;
+        };
+        const resolvedOf = (key) => parts.find((candidate) => (0, resolve_product_1.partKeyOf)(candidate) === key);
         const gapsOfPart = (key, chain) => __awaiter(void 0, void 0, void 0, function* () {
             const known = checked.get(key);
             if (known !== undefined && !chain.includes(key))
@@ -1198,43 +1360,50 @@ const partsCompletenessOf = (options) => __awaiter(void 0, void 0, void 0, funct
             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);
+            var _a, _b, _c, _d, _e;
+            const resolved = resolvedOf(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 sight = yield (0, exports.seePart)({
-                product,
-                part: resolved,
-                system,
-                base: `http://localhost:${port}`,
-                load: (id) => server.ssrLoadModule(id),
-                draw: (job) => queue.run(job),
-                sketch,
-            });
+            const sight = yield sightOf(resolved);
             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;
+            if (options.undeclaredOnly)
+                return 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);
             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 }))),
+                ...[
+                    ...(0, exports.controlStateGapsOf)({ part: key, controls: definition === null || definition === void 0 ? void 0 : definition.controls, states }),
+                    ...discoveryGapsOf({
+                        part: key,
+                        declared: (_c = (0, exports.declaredControlsOf)(definition === null || definition === void 0 ? void 0 : definition.controls)) !== null && _c !== void 0 ? _c : {},
+                        frames: seen,
+                    }).filter(isUndeclaredControlGap),
+                    ...optionProblems
+                        .filter((gap) => gap.code === 'OPTION-VALUE-MISSING')
+                        .map((gap) => (Object.assign(Object.assign({}, gap), { target: key }))),
+                ].map((gap) => `HINT ${(0, exports.completenessGapLineOf)(gap)}`),
             ]);
-            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 sketched = ((_d = product.parts.find((candidate) => (0, resolve_product_1.partKeyOf)(candidate) === key)) === null || _d === void 0 ? void 0 : _d.file) !== resolved.file;
             const reviewed = sketched || (0, merged_parts_1.readMerged)(owner.dir)[key] === hash;
             const referenced = {};
             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),
+                ...Object.values((_e = (0, exports.declaredControlsOf)(definition === null || definition === void 0 ? void 0 : definition.controls)) !== null && _e !== void 0 ? _e : {}).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) {
+                const ahead = other === null || isKitPart(other) ? undefined : resolvedOf(other);
+                if (ahead)
+                    void sightOf(ahead);
+            }
             for (const other of used)
                 if (other !== null && !(other in referenced))
                     referenced[other] = isKitPart(other) ? [] : yield gapsOfPart(other, [...chain, key]);
@@ -1242,18 +1411,21 @@ const partsCompletenessOf = (options) => __awaiter(void 0, void 0, void 0, funct
                 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,
-                    frames: seen,
-                    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,
-                }),
+                gaps: [
+                    ...(0, exports.completenessGapsOf)({
+                        part: key,
+                        controls: definition === null || definition === void 0 ? void 0 : definition.controls,
+                        states,
+                        frames: seen,
+                        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,
+                    }),
+                    ...(resolved.layer === 'pages' ? [] : (0, demo_backdrop_1.demoBackdropGapsOf)({ part: key, frames: seen })),
+                ],
             });
             exceptions.push(...excepted.listed);
             return [
@@ -1262,9 +1434,16 @@ const partsCompletenessOf = (options) => __awaiter(void 0, void 0, void 0, funct
                 ...excepted.gaps,
             ];
         });
+        for (const key of options.parts) {
+            const ahead = resolvedOf(key);
+            if (ahead)
+                void sightOf(ahead);
+        }
         const gaps = new Map();
-        for (const part of options.parts)
+        for (const part of options.parts) {
+            yield (0, run_yield_1.yieldRun)();
             gaps.set(part, yield gapsOfPart(part, []));
+        }
         return { gaps, exceptions, hints };
     }
     catch (error) {
@@ -1273,8 +1452,39 @@ const partsCompletenessOf = (options) => __awaiter(void 0, void 0, void 0, funct
         throw error;
     }
     finally {
-        yield Promise.all([queue.close(), server.close()]);
+        yield Promise.allSettled(sights.values());
+        if (!warm)
+            yield Promise.all([queue.close(), server.close()]);
     }
 });
 exports.partsCompletenessOf = partsCompletenessOf;
+/**
+ * The `CONTROL-UNDECLARED` gaps a sketch variant adds to `parts`: a control it draws at rest that no `controls`
+ * entry declares and the merged part does not draw undeclared either. Answers the gap lines, or why it could not draw.
+ */
+const addedUndeclaredControlsOf = (options) => __awaiter(void 0, void 0, void 0, function* () {
+    const { target, config, product, sketch, parts, warm } = options;
+    const drawn = yield (0, exports.partsCompletenessOf)({ target, config, product, parts, sketch, warm, undeclaredOnly: true });
+    if ('unavailable' in drawn)
+        return drawn;
+    const failed = new Map();
+    for (const [part, gaps] of drawn.gaps)
+        if (Array.isArray(gaps) && gaps.length > 0)
+            failed.set(part, gaps);
+    const merged = [...failed.keys()].filter((part) => product.parts.some((candidate) => (0, resolve_product_1.partKeyOf)(candidate) === part));
+    const before = merged.length > 0
+        ? yield (0, exports.partsCompletenessOf)({ target, config, product, parts: merged, warm, undeclaredOnly: true })
+        : null;
+    if (before && 'unavailable' in before)
+        return before;
+    const lines = [...failed].flatMap(([part, gaps]) => {
+        const known = before === null || before === void 0 ? void 0 : before.gaps.get(part);
+        const details = new Set(Array.isArray(known) ? known.map((gap) => gap.detail) : []);
+        return gaps
+            .filter((gap) => !details.has(gap.detail))
+            .map((gap) => `${(0, exports.completenessGapLineOf)(gap)} (variant ${sketch.variant})`);
+    });
+    return { lines };
+});
+exports.addedUndeclaredControlsOf = addedUndeclaredControlsOf;
 //# sourceMappingURL=complete.js.map