π¬ 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(export): render step context from an app and window when there is no url
Luis Ortiz702172a78a59
diff --git a/packages/core/src/export/__tests__/html-export.test.ts b/packages/core/src/export/__tests__/html-export.test.tsindex 200aeff..28d1309 100644--- a/packages/core/src/export/__tests__/html-export.test.ts+++ b/packages/core/src/export/__tests__/html-export.test.ts@@ -96,3 +96,32 @@ describe('exportGuideAsHTML screenshot embedding', () => {expect(rendered).toHaveBeenCalledTimes(2);});});++describe('exportGuideAsHTML mixed browser and desktop steps', () => {+ beforeEach(() => {+ rendered.mockReset();+ rendered.mockImplementation(async () => new Blob(['rendered'], { type: 'image/webp' }));+ });++ it('links a browser step and renders a desktop step as plain text', async () => {+ const browserStep = makeStep(0);+ const desktopStep: Step = {+ ...makeStep(1),+ url: '',+ app: { name: 'Excel', id: 'com.microsoft.Excel' },+ window: { title: 'Budget.xlsx' },+ };+ const shots = new Map([+ [browserStep.id, makeScreenshot(browserStep.id)],+ [desktopStep.id, makeScreenshot(desktopStep.id)],+ ]);++ const html = await render([browserStep, desktopStep], shots);++ expect(html).toContain('<a href="https://example.com/page"');+ expect(html).toContain('example.com/page');+ expect(html).toContain('Excel β Budget.xlsx');+ expect(html).not.toContain('<a href="">');+ expect(html.match(/Excel β Budget\.xlsx<\/a>/)).toBeNull();+ });+});diff --git a/packages/core/src/export/__tests__/utils.test.ts b/packages/core/src/export/__tests__/utils.test.tsindex c80865d..ee99535 100644--- a/packages/core/src/export/__tests__/utils.test.ts+++ b/packages/core/src/export/__tests__/utils.test.ts@@ -8,6 +8,7 @@ import {extractDomain,fitImage,formatDate,+ stepContext,} from '@/core/export/utils';import type { Step } from '@/core/guides/types';@@ -191,3 +192,42 @@ describe('containFit', () => {expect(containFit(0, 0, 143, 80)).toEqual({ width: 143, height: 80, x: 0, y: 0 });});});++describe('stepContext', () => {+ function step(overrides: Partial<Step>): Step {+ return {+ id: 's1',+ guideId: 'g1',+ index: 0,+ description: 'Do the thing',+ action: 'click',+ url: '',+ timestamp: 0,+ ...overrides,+ };+ }++ it('labels a browser step by host and path, and links it', () => {+ const ctx = stepContext(step({ url: 'https://www.example.com/settings/profile' }));+ expect(ctx).toEqual({ label: 'example.com/settings/profile', href: 'https://www.example.com/settings/profile' });+ });++ it('labels a desktop step by app and window, with nothing to link to', () => {+ const ctx = stepContext(step({ app: { name: 'Excel' }, window: { title: 'Budget.xlsx' } }));+ expect(ctx).toEqual({ label: 'Excel β Budget.xlsx' });+ expect(ctx?.href).toBeUndefined();+ });++ it('falls back to the app name when the window has no title', () => {+ expect(stepContext(step({ app: { name: 'Excel' }, window: { title: null } }))?.label).toBe('Excel');+ });++ it('returns nothing when a step has neither', () => {+ expect(stepContext(step({}))).toBeNull();+ });++ it('truncates at the limit the caller asks for', () => {+ const long = stepContext(step({ app: { name: 'A'.repeat(200) } }), 64);+ expect(long?.label).toHaveLength(64);+ });+});diff --git a/packages/core/src/export/docx-export.ts b/packages/core/src/export/docx-export.tsindex 806633e..1706a49 100644--- a/packages/core/src/export/docx-export.ts+++ b/packages/core/src/export/docx-export.ts@@ -22,7 +22,7 @@ import {import { i18n } from '@/core/env';import { type Branding, dataUrlToBytes, fitLogo, loadBranding } from '@/core/export/branding';import { type ExportOptions, IMAGE_SCALE_FACTORS, loadExportOptions } from '@/core/export/options';-import { blobToArrayBuffer, extractDomain, formatDate } from '@/core/export/utils';+import { blobToArrayBuffer, extractDomain, formatDate, stepContext } from '@/core/export/utils';import { actionSteps, calloutAccent, isBlock, stepNumbers, tint } from '@/core/guides/blocks';import type { Guide, Screenshot, Step } from '@/core/guides/types';import { logger } from '@/core/logger';@@ -77,16 +77,6 @@ export function fitDocxImageSize(};}-function stepUrlLabel(url: string): string {- try {- const parsed = new URL(url);- const label = `${parsed.hostname.replace(/^www\./, '')}${parsed.pathname === '/' ? '' : parsed.pathname}`;- return label.length > 64 ? `${label.slice(0, 63)}β¦` : label;- } catch {- return url;- }-}-function plainCell(children: Paragraph[], widthMm: number, rightGapMm = 0, bottom = false): TableCell {return new TableCell({borders: NO_BORDERS,@@ -307,27 +297,30 @@ async function buildStepTable(): Promise<Table> {const accent = bare(brand.accent);const stepNumber = String(number).padStart(2, '0');+ const stepCtx = opts.stepUrls ? stepContext(step, 64) : null;const textChildren: Paragraph[] = [new Paragraph({spacing: { after: 140 },children: [new TextRun({ text: step.description, bold: true, color: INK, size: 22, font: DOCX_FONT_FAMILY }),- ...(step.url && opts.stepUrls+ ...(stepCtx? [new TextRun({ text: ' Β· ', color: MUTED, size: 18, font: DOCX_FONT_FAMILY }),- new ExternalHyperlink({- link: step.url,- children: [- new TextRun({- text: stepUrlLabel(step.url),- color: accent,- underline: { type: UnderlineType.SINGLE, color: accent },- size: 18,- font: DOCX_FONT_FAMILY,- }),- ],- }),+ stepCtx.href+ ? new ExternalHyperlink({+ link: stepCtx.href,+ children: [+ new TextRun({+ text: stepCtx.label,+ color: accent,+ underline: { type: UnderlineType.SINGLE, color: accent },+ size: 18,+ font: DOCX_FONT_FAMILY,+ }),+ ],+ })+ : new TextRun({ text: stepCtx.label, color: accent, size: 18, font: DOCX_FONT_FAMILY }),]: []),],diff --git a/packages/core/src/export/html-export.ts b/packages/core/src/export/html-export.tsindex e9ac372..31eb857 100644--- a/packages/core/src/export/html-export.ts+++ b/packages/core/src/export/html-export.ts@@ -12,6 +12,7 @@ import {MAX_DESC_LINES,MAX_LEAD_LINES,MAX_TITLE_LINES,+ stepContext,} from '@/core/export/utils';import { actionSteps, calloutAccent, isBlock, stepNumbers, tint, variantLabel } from '@/core/guides/blocks';import type { Guide, Screenshot, Step } from '@/core/guides/types';@@ -57,16 +58,6 @@ function blockSection(step: Step): string {</section>`;}-function stepUrlLabel(url: string): string {- try {- const parsed = new URL(url);- const label = `${parsed.hostname.replace(/^www\./, '')}${parsed.pathname === '/' ? '' : parsed.pathname}`;- return label.length > 72 ? `${label.slice(0, 71)}β¦` : label;- } catch {- return url;- }-}-export async function exportGuideAsHTML(guide: Guide,steps: Step[],@@ -100,10 +91,12 @@ export async function exportGuideAsHTML(}const stepNumber = String(number).padStart(2, '0');- const urlHtml =- step.url && opts.stepUrls- ? `<a href="${escapeHtml(step.url)}" target="_blank" rel="noopener" style="font-size:14px;font-weight:400;color:${accent};">${escapeHtml(stepUrlLabel(step.url))}</a>`- : '';+ const ctx = opts.stepUrls ? stepContext(step) : null;+ const urlHtml = !ctx+ ? ''+ : ctx.href+ ? `<a href="${escapeHtml(ctx.href)}" target="_blank" rel="noopener" style="font-size:14px;font-weight:400;color:${accent};">${escapeHtml(ctx.label)}</a>`+ : `<span style="font-size:14px;font-weight:400;color:${accent};">${escapeHtml(ctx.label)}</span>`;stepSections.push(`<section data-step="${number}" style="display:flex;gap:8mm;margin-bottom:13mm;">diff --git a/packages/core/src/export/pdf-export.ts b/packages/core/src/export/pdf-export.tsindex a10d743..04a7691 100644--- a/packages/core/src/export/pdf-export.ts+++ b/packages/core/src/export/pdf-export.ts@@ -18,6 +18,7 @@ import {MAX_LEAD_LINES,MAX_TITLE_LINES,pxToMm,+ stepContext,} from '@/core/export/utils';import { actionSteps, calloutAccent, isBlock, stepNumbers, tint } from '@/core/guides/blocks';import type { Guide, Screenshot, Step } from '@/core/guides/types';@@ -290,8 +291,9 @@ export async function exportGuideAsPDF(let ux = TEXT_X + widthOf(doc, descLines[descLines.length - 1], 11, true);let uy = sy + 6 + (descLines.length - 1) * 5;- if (step.url && opts.stepUrls) {- const label = stepUrlLabel(step.url);+ const stepCtx = opts.stepUrls ? stepContext(step, 64) : null;+ if (stepCtx) {+ const label = stepCtx.label;doc.setFontSize(9);doc.setFont('helvetica', 'normal');const sep = ' Β· ';@@ -306,10 +308,14 @@ export async function exportGuideAsPDF(ux += sepW;}doc.setTextColor(...accent);- doc.textWithLink(label, ux, uy, { url: step.url });- doc.setDrawColor(...accent);- doc.setLineWidth(0.2);- doc.line(ux, uy + 0.9, ux + urlW, uy + 0.9);+ if (stepCtx.href) {+ doc.textWithLink(label, ux, uy, { url: stepCtx.href });+ doc.setDrawColor(...accent);+ doc.setLineWidth(0.2);+ doc.line(ux, uy + 0.9, ux + urlW, uy + 0.9);+ } else {+ doc.text(label, ux, uy);+ }}let iy = uy + 4;@@ -383,13 +389,3 @@ function drawBlock(doc: jsPDF, step: Step, y: number, nextPage: () => number): nwriteLines(doc, lines, textX, sy + CALLOUT_PAD_Y + CALLOUT_BASELINE, CALLOUT_SIZE, false, INK, CALLOUT_LINE_H);return sy + boxH + BLOCK_GAP;}--function stepUrlLabel(url: string): string {- try {- const parsed = new URL(url);- const label = `${parsed.hostname.replace(/^www\./, '')}${parsed.pathname === '/' ? '' : parsed.pathname}`;- return label.length > 64 ? `${label.slice(0, 63)}β¦` : label;- } catch {- return url;- }-}diff --git a/packages/core/src/export/utils.ts b/packages/core/src/export/utils.tsindex 45c9dcf..b09c6dd 100644--- a/packages/core/src/export/utils.ts+++ b/packages/core/src/export/utils.ts@@ -26,6 +26,32 @@ export async function blobToArrayBuffer(blob: Blob): Promise<ArrayBuffer> {return await blob.arrayBuffer();}+export interface StepContext {+ label: string;+ href?: string;+}++function truncateLabel(label: string, max: number): string {+ return label.length > max ? `${label.slice(0, max - 1)}β¦` : label;+}++export function stepContext(step: Step, max = 72): StepContext | null {+ if (step.url) {+ try {+ const parsed = new URL(step.url);+ const path = parsed.pathname === '/' ? '' : parsed.pathname;+ return { label: truncateLabel(`${parsed.hostname.replace(/^www\./, '')}${path}`, max), href: step.url };+ } catch {+ return { label: step.url, href: step.url };+ }+ }+ if (step.app) {+ const title = step.window?.title;+ return { label: truncateLabel(title ? `${step.app.name} β ${title}` : step.app.name, max) };+ }+ return null;+}+export function extractDomain(steps: Step[]): string | null {const stepWithUrl = steps.find((s) => s.url);if (!stepWithUrl) return null;diff --git a/packages/core/src/guides/types.ts b/packages/core/src/guides/types.tsindex c89468a..9402840 100644--- a/packages/core/src/guides/types.ts+++ b/packages/core/src/guides/types.ts@@ -31,6 +31,8 @@ export interface Step {description: string;action: string;url: string;+ app?: { name: string; id?: string };+ window?: { title: string | null };timestamp: number;screenshotId?: string;elementMeta?: ElementMeta;