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

package/src/lib/design/system/complete.d.ts

@@ -22,16 +22,21 @@ export type FrameBox = {
  * An element of a drawn frame that looks interactive. `control` is a native control, an interactive role or a known
  * SDK control; `unclassified` has a pointer cursor or a matched `:hover` rule and sits in no control. `marked` is the
  * `data-et-control` that declares it, `within` every `data-et-control` around it, nearest first. `owner` is the
- * embedded part whose `data-et-part` root draws it, or `null` for the frame's own part.
+ * embedded part whose `data-et-part` root draws it, or `null` for the frame's own part. `label` is its accessible name
+ * or text, which tells apart two controls at the same path.
  */
 export type FoundControl = {
     kind: 'control' | 'unclassified';
     what: string;
     path: string;
+    label?: string | null;
     marked: string | null;
     within: string[];
     owner?: string | null;
     box?: FrameBox | null;
+    covered?: boolean;
+    /** The element's `data-et-action`, or `undefined` for an element the action check does not press. */
+    action?: string | null;
 };
 /** A rule of the part's own stylesheet that sets `properties` on `path`, an element the embedded part `owner` draws. */
 export type FoundOverride = {
@@ -74,6 +79,7 @@ export type SeenFrame = {
         look?: string;
         keyboard?: boolean;
         box?: FrameBox | null;
+        covered?: boolean;
     }[];
     surfaces: {
         id: string;
@@ -82,6 +88,10 @@ export type SeenFrame = {
     }[];
     found?: FoundControl[];
     overrides?: FoundOverride[];
+    backdrop?: {
+        path: string;
+        fill: string;
+    } | null;
 };
 export type DeclaredControl = {
     kind: string;
@@ -113,6 +123,20 @@ export declare const controlStateGapsOf: (options: {
     controls: unknown;
     states: string[];
 }) => CompletenessGap[];
+/**
+ * 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`.
+ */
+export declare const introducedControlStateGapsOf: (options: {
+    part: string;
+    controls: unknown;
+    states: string[];
+    sketch: boolean;
+    base: {
+        controls: unknown;
+        states: string[];
+    } | null;
+}) => CompletenessGap[];
 /** How much of its frame one rest state changes against `base`, the first state of its part, from 0 to 1. */
 export type StateChange = {
     state: string;
@@ -150,6 +174,13 @@ export declare const completenessGapLineOf: (gap: CompletenessGap) => string;
 export declare const isMissingStateGap: (gap: CompletenessGap) => boolean;
 export declare const SDK_CONTROLS: string[];
 export declare const PLAIN_CONTROL_SELECTOR: string;
+export declare const seeFrame: (options: {
+    discover: boolean;
+    part: string;
+    ownCss: string[];
+    controlParts: Record<string, string>;
+    clip: boolean;
+}) => string;
 /** Where a rest frame of a part is drawn: its state at a preset, or at a width, as `/__design/shot` takes it. */
 export type FrameAddress = {
     state: string;

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

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.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.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");
@@ -17,6 +17,7 @@ const force_interactions_1 = require("../force-interactions");
 const serve_1 = require("../serve");
 const shot_1 = require("../shot");
 const thumb_1 = require("../thumb");
+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");
@@ -25,6 +26,7 @@ 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 KINDS = {
     disclosure: { surface: 'body', closed: 'collapsed' },
     button: { adds: ['active'] },
@@ -54,7 +56,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 +64,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 +151,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 +182,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 +223,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 +537,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 +558,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 }),
@@ -682,10 +724,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 +738,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 +799,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 +808,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 +818,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 +902,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 +1005,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 +1028,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 +1044,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 +1060,22 @@ 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 } = options;
     const context = yield browser.newContext();
     const seen = [];
     const refused = [];
     const shots = [];
     try {
         const page = yield context.newPage();
-        for (const frame of frames) {
+        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 +1095,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 +1111,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 +1125,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 {
@@ -1072,7 +1160,7 @@ const seeFrames = (options) => __awaiter(void 0, void 0, void 0, function* () {
  * 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;
+    var _a, _b, _c, _d, _e, _f;
     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 }))
@@ -1118,7 +1206,8 @@ 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 { seen, refused, changes } = yield draw((browser) => seeFrames({ browser, base, frames, part: key, ownCss, controlParts }));
     const owner = (0, inventory_approval_1.partOwnerOf)({ product, part });
     return {
         definition,
@@ -1219,13 +1308,17 @@ const partsCompletenessOf = (options) => __awaiter(void 0, void 0, void 0, funct
             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: (_b = (0, exports.declaredControlsOf)(definition === null || definition === void 0 ? void 0 : definition.controls)) !== null && _b !== void 0 ? _b : {},
+                        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 reviewed = sketched || (0, merged_parts_1.readMerged)(owner.dir)[key] === hash;
@@ -1242,18 +1335,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 [