Skip to content

armgit / mimik

Public Imported from GitHub
0

🎬 A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots πŸ“–

refactor: build every in-page overlay through one shadow host

Luis Ortizf24df2520273
diff --git a/AGENTS.md b/AGENTS.md
index c34aae6..666066f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -320,6 +320,23 @@ resolving a scancode against a keyboard layout is a local call with nothing to w
addon boundary when that flag is set, so a password never reaches our data even though UIAutomation
already withholds it.
+## Overlays We Put In The Page
+
+Five things draw into a page someone else owns: the hover ring, the blur picker, the blur panel, the
+Guide Me overlay and the recording notification. All five are the same construction β€” an element
+carrying `data-mimik-ignore` with a closed shadow root and one `<style>` β€” and `createOverlayRoot`
+builds it.
+
+Both attributes are load-bearing and neither fails loudly. Without `data-mimik-ignore` the overlay
+becomes a capture target and a blur candidate, so recording the page records our own chrome; with an
+open shadow root the page's CSS reaches in and restyles it. Five hand-written copies meant five
+chances to forget one, and three of the five had no test at all. One function has one test, and it
+asserts both invariants by construction: a closed root reads back as `null` through `host.shadowRoot`,
+which is the assertion for `mode: 'closed'`.
+
+Reading the attribute back is `isMimikElement`, in `capture/dom/element-utils.ts`. The blur picker
+had grown a private copy of it, identical line for line.
+
## Boundaries The Linter Holds
`biome.json` covers `src`, `packages/core`, `packages/ui` and `apps/desktop`. `packages/ui` was
@@ -787,6 +804,13 @@ read by main rather than by core, because none of them mean anything to the exte
`normaliseSettings` runs on every read and write, so an out-of-range delay clamps and an unknown
cursor style falls back to the platform default rather than reaching the recorder.
+`CursorStyle` and `CursorMark` are core's, not main's. The mark is written in main, crosses IPC, and
+is stored as `edits.cursor`, which the renderer reads through core's type β€” so two declarations had to
+agree by hand, and did only by luck. Main cannot value-import core, so the runtime list of styles
+still lives there, but `Record<CursorStyle, true>` makes the compiler reject it the moment core's
+union grows. That is the general shape of the fix wherever main needs one of core's closed sets: take
+the type, keep the value, let the type check the value.
+
Electron exposes no way to read the real system cursor bitmap and a screen grab never includes the
pointer, so the shapes are drawn as canvas paths. The cursor is an entry in `edits` beside the click
target, not something baked into the stored bytes, so `renderScreenshot` draws it and every exporter
diff --git a/packages/core/src/blur/panel.ts b/packages/core/src/blur/panel.ts
index ff46c48..c289aad 100644
--- a/packages/core/src/blur/panel.ts
+++ b/packages/core/src/blur/panel.ts
@@ -1,3 +1,4 @@
+import { createOverlayRoot } from '@/core/capture/dom/overlay-root';
import { i18n } from '@/core/env';
import type { PresetKey } from './regexes';
import { PRESET_LABELS } from './regexes';
@@ -253,14 +254,8 @@ export class BlurPanel {
}
mount() {
- this.host = document.createElement('div');
- this.host.setAttribute('data-mimik-ignore', '');
-
- const shadow = this.host.attachShadow({ mode: 'closed' });
-
- const style = document.createElement('style');
- style.textContent = STYLES;
- shadow.appendChild(style);
+ const { host, shadow } = createOverlayRoot(STYLES);
+ this.host = host;
this.panel = this.buildPanel();
shadow.appendChild(this.panel);
diff --git a/packages/core/src/capture/dom/__tests__/overlay-root.test.ts b/packages/core/src/capture/dom/__tests__/overlay-root.test.ts
new file mode 100644
index 0000000..bed36bb
--- /dev/null
+++ b/packages/core/src/capture/dom/__tests__/overlay-root.test.ts
@@ -0,0 +1,25 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from 'vitest';
+import { createOverlayRoot } from '@/core/capture/dom/overlay-root';
+
+describe('createOverlayRoot', () => {
+ it('marks the host so capture and blur skip it', () => {
+ const { host } = createOverlayRoot('');
+ expect(host.hasAttribute('data-mimik-ignore')).toBe(true);
+ });
+
+ it('closes the shadow root so the page cannot reach in', () => {
+ const { host } = createOverlayRoot('');
+ expect(host.shadowRoot).toBeNull();
+ });
+
+ it('adopts the styles it is given', () => {
+ const { shadow } = createOverlayRoot('.ring { color: red; }');
+ expect(shadow.querySelector('style')?.textContent).toBe('.ring { color: red; }');
+ });
+
+ it('defaults to a div and takes a custom tag', () => {
+ expect(createOverlayRoot('').host.tagName).toBe('DIV');
+ expect(createOverlayRoot('', 'mimik-notification').host.tagName).toBe('MIMIK-NOTIFICATION');
+ });
+});
diff --git a/packages/core/src/capture/dom/overlay-root.ts b/packages/core/src/capture/dom/overlay-root.ts
new file mode 100644
index 0000000..c8bf701
--- /dev/null
+++ b/packages/core/src/capture/dom/overlay-root.ts
@@ -0,0 +1,14 @@
+export interface OverlayRoot {
+ host: HTMLElement;
+ shadow: ShadowRoot;
+}
+
+export function createOverlayRoot(styles: string, tag = 'div'): OverlayRoot {
+ const host = document.createElement(tag);
+ host.setAttribute('data-mimik-ignore', '');
+ const shadow = host.attachShadow({ mode: 'closed' });
+ const style = document.createElement('style');
+ style.textContent = styles;
+ shadow.appendChild(style);
+ return { host, shadow };
+}
diff --git a/packages/core/src/capture/start-notification.ts b/packages/core/src/capture/start-notification.ts
index a83dbe5..957ac28 100644
--- a/packages/core/src/capture/start-notification.ts
+++ b/packages/core/src/capture/start-notification.ts
@@ -1,3 +1,5 @@
+import { createOverlayRoot } from '@/core/capture/dom/overlay-root';
+
const ANIMATION_DURATION_MS = 4000;
const FILL_DURATION = '2s';
const FILL_DELAY = '0.5s';
@@ -94,13 +96,7 @@ function buildMascotSVG(): string {
export function showStartNotification(): Promise<void> {
return new Promise((resolve) => {
- const host = document.createElement('mimik-notification');
- host.setAttribute('data-mimik-ignore', '');
- const shadow = host.attachShadow({ mode: 'closed' });
-
- const style = document.createElement('style');
- style.textContent = STYLES;
- shadow.appendChild(style);
+ const { host, shadow } = createOverlayRoot(STYLES, 'mimik-notification');
const wrap = document.createElement('div');
wrap.className = 'wrap';
diff --git a/packages/core/src/guideme/overlay.ts b/packages/core/src/guideme/overlay.ts
index 6a64ef0..b390b79 100644
--- a/packages/core/src/guideme/overlay.ts
+++ b/packages/core/src/guideme/overlay.ts
@@ -1,3 +1,5 @@
+import { createOverlayRoot } from '@/core/capture/dom/overlay-root';
+
const ELEMENT_TAG = 'mimik-guideme';
const PAD = 6;
@@ -71,13 +73,9 @@ export class GuideMeOverlay {
private resizeObserver: ResizeObserver | null = null;
constructor() {
- this.host = document.createElement(ELEMENT_TAG);
- this.host.setAttribute('data-mimik-ignore', '');
- this.shadow = this.host.attachShadow({ mode: 'closed' });
-
- const style = document.createElement('style');
- style.textContent = STYLES;
- this.shadow.appendChild(style);
+ const { host, shadow } = createOverlayRoot(STYLES, ELEMENT_TAG);
+ this.host = host;
+ this.shadow = shadow;
document.documentElement.appendChild(this.host);
}
diff --git a/src/blur/element-picker.ts b/src/blur/element-picker.ts
index 5ac7bc9..8956d23 100644
--- a/src/blur/element-picker.ts
+++ b/src/blur/element-picker.ts
@@ -1,4 +1,6 @@
import { i18n } from '#imports';
+import { isMimikElement } from '@/core/capture/dom/element-utils';
+import { createOverlayRoot } from '@/core/capture/dom/overlay-root';
import { HoverRing } from '@/lib/hover-ring';
const MANUAL_CLASS = 'mimik-manual-blur';
@@ -85,13 +87,8 @@ export class ElementPicker {
}
private mount() {
- this.host = document.createElement('div');
- this.host.setAttribute('data-mimik-ignore', '');
-
- const shadow = this.host.attachShadow({ mode: 'closed' });
- const style = document.createElement('style');
- style.textContent = STYLES;
- shadow.appendChild(style);
+ const { host, shadow } = createOverlayRoot(STYLES);
+ this.host = host;
const bar = document.createElement('div');
bar.className = 'bar';
@@ -111,19 +108,15 @@ export class ElementPicker {
document.documentElement.appendChild(this.host);
}
- private isMimikElement(el: Element): boolean {
- return !!el.closest('[data-mimik-ignore]');
- }
-
private suppress(e: Event) {
- if (e.target instanceof Element && this.isMimikElement(e.target)) return;
+ if (e.target instanceof Element && isMimikElement(e.target)) return;
e.stopImmediatePropagation();
}
private onClick(e: Event) {
const raw = (e as MouseEvent).target;
if (!raw || !(raw instanceof HTMLElement)) return;
- if (this.isMimikElement(raw)) return;
+ if (isMimikElement(raw)) return;
e.preventDefault();
e.stopImmediatePropagation();
this.toggleBlur(raw);
@@ -141,7 +134,7 @@ export class ElementPicker {
private onMouseOver(e: Event) {
const raw = (e as MouseEvent).target;
- if (!raw || !(raw instanceof HTMLElement) || this.isMimikElement(raw)) return;
+ if (!raw || !(raw instanceof HTMLElement) || isMimikElement(raw)) return;
this.ring.show(raw);
}
diff --git a/src/lib/hover-ring.ts b/src/lib/hover-ring.ts
index cdd4a52..9f1f28b 100644
--- a/src/lib/hover-ring.ts
+++ b/src/lib/hover-ring.ts
@@ -1,3 +1,5 @@
+import { createOverlayRoot } from '@/core/capture/dom/overlay-root';
+
const PAD = 3;
const Z_INDEX = 2147483644;
const COLOR_VAR = '--mimik-ring-color';
@@ -46,16 +48,10 @@ export class HoverRing {
}
private mount(): HTMLElement {
- const host = document.createElement('div');
- host.setAttribute('data-mimik-ignore', '');
+ const { host, shadow } = createOverlayRoot(STYLES);
host.style.cssText = `position:fixed;inset:0;z-index:${Z_INDEX};pointer-events:none;`;
host.style.setProperty(COLOR_VAR, this.color);
- const shadow = host.attachShadow({ mode: 'closed' });
- const style = document.createElement('style');
- style.textContent = STYLES;
- shadow.appendChild(style);
-
const ring = document.createElement('div');
ring.className = 'ring';
shadow.appendChild(ring);