π¬ 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
feat(desktop): show shortcuts with macOS symbols and in a chip inside key steps
Luis Ortiz199be3aec020
diff --git a/apps/desktop/scripts/check-overlay.ts b/apps/desktop/scripts/check-overlay.tsindex d0bfab3..e07263e 100644--- a/apps/desktop/scripts/check-overlay.ts+++ b/apps/desktop/scripts/check-overlay.ts@@ -221,7 +221,7 @@ app.whenReady().then(async () => {`badge ${badgeWhileRecording.badge}, paused tip ${resting.tip}, mascot shown ${resting.intro}`,);- overlay.showStep({ id: 'one', index: 1, title: 'Click "Save"', src, source: 'heuristic', pending: false, app: 'Explorer' });+ overlay.showStep({ id: 'one', index: 1, title: 'Click "Save"', action: 'click', src, source: 'heuristic', pending: false, app: 'Explorer' });await settle();const step = await card("intro: getComputedStyle(document.querySelector('#intro')).display, title: document.querySelector('#stepTitle').textContent, source: document.querySelector('#source').textContent, meta: document.querySelector('#metaText').textContent",@@ -232,12 +232,12 @@ app.whenReady().then(async () => {`intro display: ${step.intro}, title: ${step.title}, source: ${step.source}, meta: ${step.meta}`,);- overlay.showStep({ id: 'one', index: 1, title: 'Click "Save"', src, source: 'heuristic', pending: true, app: 'Explorer' });+ overlay.showStep({ id: 'one', index: 1, title: 'Click "Save"', action: 'click', src, source: 'heuristic', pending: true, app: 'Explorer' });await settle();const pendingStep = await card("title: document.querySelector('#stepTitle').textContent, source: document.querySelector('#source').textContent, loaders: document.querySelectorAll('#writing, #skeleton, #pillWriting').length",);- overlay.showStep({ id: 'one', index: 1, title: 'Save the file', src, source: 'ai', pending: false, app: 'Explorer' });+ overlay.showStep({ id: 'one', index: 1, title: 'Save the file', action: 'click', src, source: 'ai', pending: false, app: 'Explorer' });await settle();const rewritten = await card("source: document.querySelector('#source').textContent, title: document.querySelector('#stepTitle').textContent");check(@@ -250,6 +250,17 @@ app.whenReady().then(async () => {`while pending: ${pendingStep.source} "${pendingStep.title}", ${pendingStep.loaders} writing loaders; then ${rewritten.source} "${rewritten.title}"`,);+ overlay.showStep({ id: 'one', index: 1, title: 'Press βS on "Search"', action: 'keydown:βS', src, source: 'heuristic', pending: false, app: 'Chrome' });+ await settle();+ const keyed = await card(+ "key: document.querySelector('#stepTitle kbd')?.textContent ?? null, title: document.querySelector('#stepTitle').textContent",+ );+ check(+ 'a key step shows its shortcut in a chip, like the tip',+ keyed.key === 'βS' && keyed.title === 'Press βS on "Search"',+ `chip ${keyed.key}, title "${keyed.title}"`,+ );+await evaluate("document.querySelector('#remove').click()");await settle();check('removing the step reaches the host', commands.includes('remove'), `commands: ${commands.join(', ')}`);@@ -291,13 +302,13 @@ app.whenReady().then(async () => {aimed.src === src,`before: marker ${unaimed.aim}, developing ${unaimed.developing}; after: marker ${aimed.aim} at ${aimed.left}, developing ${aimed.developing}`,);- overlay.showStep({ id: 'two', index: 2, title: 'Click "Open"', src, source: 'heuristic', pending: true, app: 'Explorer' });+ overlay.showStep({ id: 'two', index: 2, title: 'Click "Open"', action: 'click', src, source: 'heuristic', pending: true, app: 'Explorer' });overlay.setBusy(false);await settle();const describing = await card("printer: !document.querySelector('#printer').hidden, title: getComputedStyle(document.querySelector('#stepTitle')).visibility",);- overlay.showStep({ id: 'two', index: 2, title: 'Open the file', src, source: 'ai', pending: false, app: 'Explorer' });+ overlay.showStep({ id: 'two', index: 2, title: 'Open the file', action: 'click', src, source: 'ai', pending: false, app: 'Explorer' });await new Promise((resolve) => setTimeout(resolve, 900));await settle();const aiLanded = await card(@@ -313,10 +324,10 @@ app.whenReady().then(async () => {`while describing: printer ${describing.printer}, title ${describing.title}; landed: printer ${aiLanded.printer}, ${aiLanded.source} "${aiLanded.title}"`,);const shortTitle = await card("height: document.body.scrollHeight, preview: document.querySelector('#preview').offsetHeight");- overlay.showStep({ id: 'one', index: 1, title: 'Click '.repeat(40), src, source: 'ai', pending: false, app: 'Explorer' });+ overlay.showStep({ id: 'one', index: 1, title: 'Click '.repeat(40), action: 'click', src, source: 'ai', pending: false, app: 'Explorer' });await settle();const longTitle = await card("height: document.body.scrollHeight, preview: document.querySelector('#preview').offsetHeight");- overlay.showStep({ id: 'one', index: 1, title: 'Save the file', src, source: 'ai', pending: false, app: 'Explorer' });+ overlay.showStep({ id: 'one', index: 1, title: 'Save the file', action: 'click', src, source: 'ai', pending: false, app: 'Explorer' });await settle();check('the card keeps its height when a step lands, and a long title takes it from the screenshot',diff --git a/apps/desktop/scripts/check-pipeline.ts b/apps/desktop/scripts/check-pipeline.tsindex 569e2d8..11f23c3 100644--- a/apps/desktop/scripts/check-pipeline.ts+++ b/apps/desktop/scripts/check-pipeline.ts@@ -457,7 +457,8 @@ app.whenReady().then(async () => {name: 'a shortcut is its own step',ok:shortcut?.action === 'keydown:Ctrl+S' &&- comboLabel(pressed(31, { ctrl: true, shift: true }), 'S') === 'Ctrl+Shift+S' &&+ comboLabel(pressed(31, { ctrl: true, shift: true }), 'S', false) === 'Ctrl+Shift+S' &&+ comboLabel(pressed(31, { meta: true, shift: true, alt: true }), 'S', true) === 'β₯β§βS' &&unnamed === null &&isRepeatKey({ keycode: 28, at: 1_000 }, 28, 1_400) &&!isRepeatKey({ keycode: 28, at: 1_000 }, 28, 1_600) &&diff --git a/apps/desktop/src/main/capture/recorder.ts b/apps/desktop/src/main/capture/recorder.tsindex 411a620..ffdc190 100644--- a/apps/desktop/src/main/capture/recorder.ts+++ b/apps/desktop/src/main/capture/recorder.ts@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';import type { CaptureImage } from '@mimik/core/capture/sink';import type { ElementMeta } from '@mimik/core/guides/types';import { clipboard, screen } from 'electron';+import { shortcutLabel } from '../../renderer/lib/shortcut-label';import { cursorPoint } from './displays';import {clearDeadKey,@@ -143,14 +144,13 @@ export function isRepeatKey(previous: { keycode: number; at: number } | null, kereturn previous !== null && previous.keycode === keycode && at - previous.at <= REPEAT_CLICK_MS;}-export function comboLabel(action: KeyAction, key: string): string {+export function comboLabel(action: KeyAction, key: string, mac = process.platform === 'darwin'): string {const held: string[] = [];- const mac = process.platform === 'darwin';- if (action.meta) held.push(mac ? 'Cmd' : 'Meta');+ if (action.meta) held.push(mac ? 'Command' : 'Meta');if (action.ctrl) held.push('Ctrl');- if (action.alt) held.push(mac ? 'Option' : 'Alt');+ if (action.alt) held.push('Alt');if (action.shift) held.push('Shift');- return [...held, key].join('+');+ return mac ? shortcutLabel([...held, key].join('+'), true) : [...held, key].join('+');}export function clickAction(button: number): string {diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.tsindex bbe95a4..a2297bf 100644--- a/apps/desktop/src/main/index.ts+++ b/apps/desktop/src/main/index.ts@@ -1,6 +1,7 @@import { readFile } from 'node:fs/promises';import { basename, join } from 'node:path';import { app, BrowserWindow, dialog, ipcMain, Menu, nativeImage, protocol, screen, shell, Tray } from 'electron';+import { shortcutLabel } from '../renderer/lib/shortcut-label';import { registerAiFetch } from './ai-fetch';import { APP_ICON_SCHEME, registerAppIconProtocol } from './app-icon';import { ask } from './ask';@@ -403,8 +404,8 @@ if (!app.requestSingleInstanceLock()) {});captureSettings = loadSettings();- const shortcutLabel = (accelerator: string | null) =>- accelerator?.replace(/CommandOrControl|CmdOrCtrl/g, process.platform === 'darwin' ? 'Cmd' : 'Ctrl') || null;+ const labelOf = (accelerator: string | null) =>+ accelerator ? shortcutLabel(accelerator, process.platform === 'darwin') : null;overlay = new CaptureOverlay((command) => void onOverlayCommand(command),() => (captureSettings ?? loadSettings()).captureMode,@@ -416,7 +417,7 @@ if (!app.requestSingleInstanceLock()) {},shortcuts: () => {const { shortcuts } = captureSettings ?? loadSettings();- return { startStop: shortcutLabel(shortcuts.startStop), capture: shortcutLabel(shortcuts.capture) };+ return { startStop: labelOf(shortcuts.startStop), capture: labelOf(shortcuts.capture) };},},);@@ -437,6 +438,7 @@ if (!app.requestSingleInstanceLock()) {id: reply.stepId,index: steps.length + 1 + (insert?.afterStep ?? 0),title: reply.title,+ action: request.action,src: request.image?.src ?? '',source: 'heuristic',pending: reply.pending === true,diff --git a/apps/desktop/src/main/overlay/index.ts b/apps/desktop/src/main/overlay/index.tsindex 1fcd817..368dc8c 100644--- a/apps/desktop/src/main/overlay/index.ts+++ b/apps/desktop/src/main/overlay/index.ts@@ -23,6 +23,7 @@ export interface OverlayStep {id: string;index: number;title: string;+ action: string;src: string;source: 'heuristic' | 'ai';pending: boolean;diff --git a/apps/desktop/src/renderer/lib/shortcut-label.ts b/apps/desktop/src/renderer/lib/shortcut-label.tsnew file mode 100644index 0000000..3a5ab53--- /dev/null+++ b/apps/desktop/src/renderer/lib/shortcut-label.ts@@ -0,0 +1,27 @@+const MAC_SYMBOLS: Record<string, string> = {+ control: 'β',+ ctrl: 'β',+ alt: 'β₯',+ altgr: 'β₯',+ option: 'β₯',+ shift: 'β§',+ command: 'β',+ cmd: 'β',+ commandorcontrol: 'β',+ cmdorctrl: 'β',+ super: 'β',+ meta: 'β',+};+const MAC_ORDER = ['β', 'β₯', 'β§', 'β'];++export function shortcutLabel(accelerator: string, mac: boolean): string {+ const parts = accelerator+ .split('+')+ .map((part) => part.trim())+ .filter(Boolean);+ const key = parts.pop() ?? '';+ if (!mac)+ return [...parts.map((part) => (/^(commandorcontrol|cmdorctrl)$/i.test(part) ? 'Ctrl' : part)), key].join('+');+ const held = new Set(parts.map((part) => MAC_SYMBOLS[part.toLowerCase()] ?? part));+ return [...MAC_ORDER.filter((symbol) => held.has(symbol)), key].join('');+}diff --git a/apps/desktop/src/renderer/overlay.css b/apps/desktop/src/renderer/overlay.cssindex 4eb34e9..2a4f8ff 100644--- a/apps/desktop/src/renderer/overlay.css+++ b/apps/desktop/src/renderer/overlay.css@@ -772,7 +772,8 @@ body.controls #keyHint strong {font-weight: 600;}-body.controls #hintKey {+body.controls #hintKey,+body.controls #stepTitle kbd {padding: 1px 6px;border: 1px solid var(--lavender);border-radius: 5px;@@ -784,6 +785,10 @@ body.controls #hintKey {font-weight: 600;}+body.controls #stepTitle kbd {+ font-size: 0.85em;+}+body.controls #modeBlock {padding: 14px 14px 0;}diff --git a/apps/desktop/src/renderer/overlay/controls.ts b/apps/desktop/src/renderer/overlay/controls.tsindex ecb2a30..676c4cd 100644--- a/apps/desktop/src/renderer/overlay/controls.ts+++ b/apps/desktop/src/renderer/overlay/controls.ts@@ -1,4 +1,5 @@import { aiFailureNotice } from '@mimik/core/capture/ai/errors';+import { splitAtShortcut } from '@mimik/core/capture/split-at-shortcut';import { i18n } from '@mimik/core/env';import type { OverlayView } from '../../main/overlay';import { icon } from '../icons';@@ -234,7 +235,10 @@ export function controls(): void {veil.hidden = !paused || capturing;remove.hidden = !step || capturing || armed;- stepTitle.textContent = step?.title ?? '\u00a0';+ const title = step?.title ?? '\u00a0';+ const split = splitAtShortcut(title, step?.action);+ if (split) stepTitle.replaceChildren(split[0], el('kbd', {}, split[1]), split[2]);+ else stepTitle.textContent = title;const extra = stepTitle.getBoundingClientRect().height - Number.parseFloat(getComputedStyle(stepTitle).lineHeight);preview.style.setProperty('--title-extra', `${step ? Math.max(0, extra) : 0}px`);source.hidden = !step;diff --git a/apps/desktop/src/renderer/settings/ShortcutRecorder.tsx b/apps/desktop/src/renderer/settings/ShortcutRecorder.tsxindex 3ab035d..728cc76 100644--- a/apps/desktop/src/renderer/settings/ShortcutRecorder.tsx+++ b/apps/desktop/src/renderer/settings/ShortcutRecorder.tsx@@ -2,7 +2,11 @@ import { i18n } from '@mimik/core/env';import { Button } from '@mimik/ui';import { X } from 'lucide-react';import { useState } from 'react';+import { shortcutLabel } from '../lib/shortcut-label';import { accelerator } from './lib/accelerator';++const MAC = navigator.userAgent.includes('Mac');+import { Row } from './Row';interface ShortcutRecorderProps {@@ -35,7 +39,7 @@ export function ShortcutRecorder({ label, value, onChange }: ShortcutRecorderPro: 'border-border bg-card text-foreground hover:border-violet'}`}>- {listening ? i18n.t('desktop_shortcutPress') : (value ?? 'β')}+ {listening ? i18n.t('desktop_shortcutPress') : value ? shortcutLabel(value, MAC) : 'β'}</button><Buttontype="button"diff --git a/packages/core/src/capture/__tests__/split-at-shortcut.test.ts b/packages/core/src/capture/__tests__/split-at-shortcut.test.tsnew file mode 100644index 0000000..4fdd8a7--- /dev/null+++ b/packages/core/src/capture/__tests__/split-at-shortcut.test.ts@@ -0,0 +1,13 @@+import { describe, expect, it } from 'vitest';+import { splitAtShortcut } from '../split-at-shortcut';++describe('splitAtShortcut', () => {+ it('splits a key step title around its shortcut', () => {+ expect(splitAtShortcut('Press βS on "Search"', 'keydown:βS')).toEqual(['Press ', 'βS', ' on "Search"']);+ });++ it('leaves other steps and titles without the shortcut alone', () => {+ expect(splitAtShortcut('Click "Save"', 'click')).toBeNull();+ expect(splitAtShortcut('Save the file', 'keydown:βS')).toBeNull();+ });+});diff --git a/packages/core/src/capture/split-at-shortcut.ts b/packages/core/src/capture/split-at-shortcut.tsnew file mode 100644index 0000000..717def6--- /dev/null+++ b/packages/core/src/capture/split-at-shortcut.ts@@ -0,0 +1,8 @@+const KEY_ACTION = 'keydown:';++export function splitAtShortcut(text: string, action: string | undefined): [string, string, string] | null {+ if (!action?.startsWith(KEY_ACTION)) return null;+ const key = action.slice(KEY_ACTION.length);+ const at = key ? text.indexOf(key) : -1;+ return at < 0 ? null : [text.slice(0, at), key, text.slice(at + key.length)];+}diff --git a/packages/core/src/export/html-export.ts b/packages/core/src/export/html-export.tsindex dc818b6..2906b4c 100644--- a/packages/core/src/export/html-export.ts+++ b/packages/core/src/export/html-export.ts@@ -1,3 +1,4 @@+import { splitAtShortcut } from '@/core/capture/split-at-shortcut';import { i18n } from '@/core/env';import { fitLogo, loadBranding } from '@/core/export/branding';import { type ExportOptions, IMAGE_SCALE_FACTORS, loadExportOptions } from '@/core/export/options';@@ -43,6 +44,13 @@ function embedScreenshot(screenshot: Screenshot): Promise<EmbeddedImage> {return image;}+function titleHtml(step: Step): string {+ const split = splitAtShortcut(step.description, step.action);+ if (!split) return escapeHtml(step.description);+ const [before, key, after] = split.map(escapeHtml);+ return `${before}<kbd style="font:inherit;font-size:.85em;padding:1px 6px;border:1px solid #C7D2FE;border-radius:5px;background:#fff;white-space:nowrap;">${key}</kbd>${after}`;+}+function blockSection(step: Step): string {if (step.blockType === 'heading') {return `@@ -103,7 +111,7 @@ export async function exportGuideAsHTML(<section data-step="${number}" style="display:flex;gap:8mm;margin-bottom:13mm;"><div style="flex:0 0 22mm;font-size:34px;font-weight:700;color:${accent};line-height:.9;">${stepNumber}</div><div style="flex:1;min-width:0;border-top:1px solid #1E1B4B;padding-top:6px;">- <p style="margin:0;font-size:17px;font-weight:700;line-height:1.45;color:#1E1B4B;overflow-wrap:anywhere;">${escapeHtml(step.description)}${+ <p style="margin:0;font-size:17px;font-weight:700;line-height:1.45;color:#1E1B4B;overflow-wrap:anywhere;">${titleHtml(step)}${urlHtml ? `<span style="color:#6B7280;font-weight:400;"> Β· </span>${urlHtml}` : ''}</p>${imgHtml}diff --git a/packages/ui/src/guide/components/StepCard.tsx b/packages/ui/src/guide/components/StepCard.tsxindex e1a8218..436f973 100644--- a/packages/ui/src/guide/components/StepCard.tsx+++ b/packages/ui/src/guide/components/StepCard.tsx@@ -1,3 +1,4 @@+import { splitAtShortcut } from '@mimik/core/capture/split-at-shortcut';import { i18n } from '@mimik/core/env';import { replaceScreenshot, restoreNarratedDescription } from '@mimik/core/guides/service';import type { Screenshot, Step } from '@mimik/core/guides/types';@@ -46,6 +47,7 @@ export function StepCard({hasApiKey,}: StepCardProps) {const [description, setDescription] = useState(step.description);+ const shortcut = splitAtShortcut(step.description, step.action);const [dragOver, setDragOver] = useState(false);const [copied, setCopied] = useState(false);const [confirmDelete, setConfirmDelete] = useState(false);@@ -150,7 +152,17 @@ export function StepCard({</span>) : readOnly ? (<p className="text-[13px] font-medium leading-snug flex-1 text-foreground whitespace-pre-wrap">- {step.description}+ {shortcut ? (+ <>+ {shortcut[0]}+ <kbd className="rounded-[5px] border border-border bg-card px-1.5 py-px font-[inherit] text-[0.85em] font-semibold whitespace-nowrap">+ {shortcut[1]}+ </kbd>+ {shortcut[2]}+ </>+ ) : (+ step.description+ )}</p>) : (<textarea