π¬ A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots π
TypeScript browser-extensionchrome-extensiondocumentationfirefox-extensionguide-generatorlocal-firstmanifest-v3privacy-firstproductivityreactscreenshotstep-by-step-guidetutorialtypescriptworkflowwxt
refactor: build every in-page overlay through one shadow host
Luis Ortizf24df2520273
diff --git a/AGENTS.md b/AGENTS.mdindex 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 waddon boundary when that flag is set, so a password never reaches our data even though UIAutomationalready 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 unknowncursor 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 thepointer, so the shapes are drawn as canvas paths. The cursor is an entry in `edits` beside the clicktarget, not something baked into the stored bytes, so `renderScreenshot` draws it and every exporterdiff --git a/packages/core/src/blur/panel.ts b/packages/core/src/blur/panel.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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);