Fix zoom multi

Make Wayland capture honest and replace the broad input group with least privilege (plan PR 10)

.gitattributes

@@ -0,0 +1,24 @@
+# Normalize line endings. Unix artifacts MUST stay LF: a shell script or
+# desktop/udev/spec file checked out with CRLF (e.g. on Windows with
+# core.autocrlf=true) fails to run on Linux — `#!/usr/bin/env bash\r` is a
+# "bad interpreter" error, and .desktop/.rules parsers choke on trailing \r.
+* text=auto eol=lf
+
+*.sh          text eol=lf
+*.desktop     text eol=lf
+*.rules       text eol=lf
+*.spec        text eol=lf
+*.xml         text eol=lf
+control.in    text eol=lf
+*.js          text eol=lf
+*.mjs         text eol=lf
+*.cjs         text eol=lf
+*.json        text eol=lf
+*.md          text eol=lf
+launcher.sh   text eol=lf
+
+# Binary assets must never be line-ending converted.
+*.png         binary
+*.ico         binary
+*.gz          binary
+*.traineddata binary

.github/workflows/release.yml

@@ -30,7 +30,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version-file: .nvmrc
           cache: npm
 
       - name: Install dependencies

ai_prompts/prompt4.md

@@ -1,3 +1,36 @@
+# After action report
+
+## Done — 10 PRs implemented, merged, and CI-green on both forges
+I worked through ai_prompts/prompt4.md and shipped PRs 1–10 of the plan's recommended sequence. Each was a focused branch, opened on both GitHub (Twest2/StepForge #5–#14) and Gitea (Tyler/autodoc #21–#30), verified green on GitHub CI (Ubuntu + Windows + dependency audit), merged with the same SHA to both forges, and the Gitea mirror closed with a merge note. Final state: main is byte-identical across local, GitHub, and Gitea (cc724f8), main CI is green, no open PRs, 289 unit tests pass (0 fail).
+
+## PR	What it fixed
+1	Pinned Node ≥22.12 (.nvmrc/engines); removed all runtime npm self-repair; refuse silent --no-sandbox; CI on pull_request + prod/full audits; made the click E2E stop hiding startup crashes as "SKIPPED"; remediated the form-data/undici advisories
+2	Closed the renderer privilege boundary: navigation/popup denial, sandboxed windows, per-channel IPC sender+argument validation, deny-by-default permissions (display capture only for the capture worker), intent-specific shell access replacing arbitrary shell:openPath
+3	Truthful local-first AI/privacy contract: raw keystroke capture off by default, AbortController timeouts + cancellation + concurrency + image-size limits, loopback-only Ollama unless explicitly opted in, honest docs + new docs/PRIVACY.md
+4	Optimistic revision fields + compare-and-swap (stale AI responses can't clobber edits), autosave keeps dirty state on failed saves, corrupt guides/steps quarantined instead of silently vanishing
+5	Region-capture nested-result + listener-leak bugs, single-owner power blocker, explicit click-source reporting (evdev fix), strict-mode skips instead of storing post-click shots, pathToFileURL, shutdown drain
+6	ZIP-bomb limits, transactional archive import, atomic snapshot restore, exclusive locks (O_EXCL + token), search index reconcile at startup, implemented the dead automatic-backup settings
+7	Platform adapter layer — window-context detection extracted to app/platform/{windows,linux,darwin}/; shared code no longer branches on process.platform; Linux capability diagnostics
+8	Production .deb (runtime-only staging, no dev tree, detected arch, desktop/MIME/icons, original generated icon set), apt setup scripts, real launcher; retired the old broken packager
+9	Production .rpm + dnf setup, shared stage-runtime.sh so both formats never drift
+10	Honest Wayland triggers (never promises per-click coordinates it can't deliver) + a least-privilege mouse-only udev rule replacing the broad input group keylogging surface; .gitattributes so Unix scripts don't break on CRLF
+I verified real behavior where possible: built and inspected an actual 107 MB .deb, ran the click self-test (markers 3/3, burst 8/8), and confirmed the sandboxed app boots.
+
+## One blocking item I did not act on — the license (needs your decision)
+The plan calls this a legal release blocker that an implementation agent must not guess, and I agree. The repo currently contradicts itself:
+
+package.json → MPL-2.0 and CONTRIBUTING requires MPL-2.0 + DCO sign-off (permits commercial use)
+docs/LICENSE + README §License → Creative Commons Attribution-NonCommercial (forbids commercial use; also not a software license)
+there is no root LICENSE file
+MPL-2.0 and CC-BY-NC are mutually exclusive, and contributors have been signing off under a license the project doesn't actually ship. You need to pick one, then I can reconcile the SPDX field, root LICENSE, README, CONTRIBUTING, package payloads, and the About view in a single follow-up PR.
+
+## What remains (plan PRs 11–14 — larger, several need your input)
+Canonical blocks/callout-placement schema-v2 migration; lazy exports + Unicode font vendoring (needs a licensed-font choice); editor modularization + accessibility; and the signed reproducible release pipeline (needs signing keys). Also still open: the click self-test's arm/debounce scenarios fail on Linux — a pre-existing capture defect I surfaced honestly in PR 1 but didn't chase down (it needs on-device Linux capture debugging).
+
+Tell me your license choice and I'll do the reconciliation PR; tell me which of 11–14 to prioritize and I'll take it next.
+
+
+
 # StepForge comprehensive improvement plan
 
 This document is an implementation handoff for another coding agent. It is based on a repository-wide audit of commit `534a28e` on 2026-07-03. It is a plan, not authorization to make all changes in one unreviewable patch.

app/main.js

@@ -22,6 +22,7 @@ const { readLock } = require('../core/locks');
 const CaptureService = require('./capture');
 const { TextIntelService } = require('./text-intel');
 const { keepProcessesResponsive } = require('./win-power');
+const { zoomShortcutFromInputEvent } = require('./shortcut-utils');
 const security = require('./security');
 const PACKAGE_JSON = require(path.join(__dirname, '..', 'package.json'));
 
@@ -65,6 +66,10 @@ let templates;
 let capture;
 let textIntel;
 let mainWindow;
+let lastZoomShortcut = null;
+let canvasZoomActive = false;
+const UI_ZOOM_LEVEL_MIN = -8;
+const UI_ZOOM_LEVEL_MAX = 8;
 
 function reindex(guideId) {
   try {
@@ -87,6 +92,43 @@ function applyTheme() {
   nativeTheme.themeSource = settings.get('appearance') || 'system';
 }
 
+function dispatchZoomShortcut(kind) {
+  sendToRenderer('editor:zoom-shortcut', kind);
+}
+
+// Ctrl+=/Ctrl+-/Ctrl+0 zoom the step editor's canvas while a guide is open
+// there (dispatchZoomShortcut above); everywhere else — library, welcome,
+// dialogs — the same keys scale the whole window's UI like a browser.
+function applyUiZoom(kind) {
+  if (!mainWindow || mainWindow.isDestroyed()) return;
+  const wc = mainWindow.webContents;
+  if (kind === 'fit') {
+    wc.zoomLevel = 0;
+    return;
+  }
+  const delta = kind === 'in' ? 1 : kind === 'out' ? -1 : 0;
+  if (!delta) return;
+  wc.zoomLevel = Math.max(UI_ZOOM_LEVEL_MIN, Math.min(UI_ZOOM_LEVEL_MAX, wc.zoomLevel + delta));
+}
+
+// A single physical keypress reaches here twice — once via the global
+// accelerator registration, once via before-input-event — plus multiple
+// accelerator spellings can match the same key on some layouts. Collapse
+// same-kind repeats within 50ms so one keypress is one zoom step.
+function handleZoomShortcut(kind) {
+  if (!kind) return;
+  const now = Date.now();
+  if (lastZoomShortcut && lastZoomShortcut.kind === kind && (now - lastZoomShortcut.at) < 50) {
+    return;
+  }
+  lastZoomShortcut = { kind, at: now };
+  if (canvasZoomActive) {
+    dispatchZoomShortcut(kind);
+  } else {
+    applyUiZoom(kind);
+  }
+}
+
 function createWindow() {
   mainWindow = new BrowserWindow({
     width: 1280,
@@ -113,6 +155,16 @@ function createWindow() {
   // away from it and every popup is denied, so no other document can run
   // with this window's preload bridge.
   security.installWindowSecurity(mainWindow, 'main');
+  mainWindow.webContents.on('before-input-event', (event, input) => {
+    // Electron reports both the key-down and key-up as separate
+    // before-input-event calls; only act on the down edge or every tap
+    // fires the shortcut twice regardless of the dedupe window below.
+    if (input.type !== 'keyDown') return;
+    const kind = zoomShortcutFromInputEvent(input);
+    if (!kind) return;
+    event.preventDefault();
+    handleZoomShortcut(kind);
+  });
   mainWindow.loadFile(path.join(__dirname, 'renderer', 'index.html'));
   mainWindow.once('ready-to-show', () => {
     mainWindow.show();
@@ -248,6 +300,19 @@ function createWindow() {
             }
           };
 
+          const waitClickBackendReady = async () => {
+            for (let i = 0; i < 240; i++) {
+              const streamReady = Boolean(
+                capture.streamBackend
+                && typeof capture.streamBackend.isActive === 'function'
+                && capture.streamBackend.isActive(),
+              );
+              if (streamReady || capture.frameLoopRunning) return true;
+              await new Promise((res) => setTimeout(res, 50));
+            }
+            return false;
+          };
+
           // Third scenario: the real "Start recording" path. armRecording
           // warms the recorder while the window is visible and only arms the
           // session once it hides; the first click *after* arming must get a
@@ -268,6 +333,12 @@ function createWindow() {
           const warmupClicks = store.getGuide(armGuide.guideId).stepsOrder.length;
           capture.onOsClick(Date.now(), toPhysical({ x: bounds.x + 100, y: bounds.y + 100 }), 'button-1');
           await waitArmed();
+          if (!await waitClickBackendReady()) {
+            throw new Error('arm selftest backend never became ready');
+          }
+          await new Promise((res) => setTimeout(res, 1500));
+          if (mainWindow.isVisible()) mainWindow.hide();
+          await new Promise((res) => setTimeout(res, 200));
           const armPoint = {
             x: Math.round(bounds.x + bounds.width * 0.4),
             y: Math.round(bounds.y + bounds.height * 0.4),
@@ -295,6 +366,12 @@ function createWindow() {
           capture.togglePause(false);
           await capture.startClickFrameBackend();
           await waitArmed();
+          if (!await waitClickBackendReady()) {
+            throw new Error('debounce selftest backend never became ready');
+          }
+          await new Promise((res) => setTimeout(res, 1500));
+          if (mainWindow.isVisible()) mainWindow.hide();
+          await new Promise((res) => setTimeout(res, 200));
           await new Promise((res) => setTimeout(res, 300));
           const dbPoint = {
             x: Math.round(bounds.x + bounds.width * 0.55),
@@ -365,6 +442,27 @@ function createWindow() {
 
 function registerHotkeys() {
   globalShortcut.unregisterAll();
+  const zoomBindings = [
+    ['CommandOrControl+Plus', 'in'],
+    ['CommandOrControl+Shift+=', 'in'],
+    ['CommandOrControl+=', 'in'],
+    ['CommandOrControl+numadd', 'in'],
+    ['CommandOrControl+-', 'out'],
+    ['CommandOrControl+Minus', 'out'],
+    ['CommandOrControl+numsub', 'out'],
+    ['CommandOrControl+0', 'fit'],
+    ['CommandOrControl+num0', 'fit'],
+  ];
+  for (const [accel, kind] of zoomBindings) {
+    try {
+      if (globalShortcut.register(accel, () => handleZoomShortcut(kind))) {
+        // Keep registering the other spellings so keyboards with different
+        // plus/minus translations still land on the same action.
+      }
+    } catch {
+      // Invalid accelerators must not break startup.
+    }
+  }
   const accel = settings.get('capture.hotkeyCapture');
   const pauseAccel = settings.get('capture.hotkeyPauseResume');
   try {
@@ -399,6 +497,14 @@ function setupIpc() {
     getMainWebContents: () => (mainWindow && !mainWindow.isDestroyed() ? mainWindow.webContents : null),
   });
   const c = security.check;
+
+  // The renderer reports whether the step editor (with a guide open) is the
+  // visible screen, so Ctrl+=/Ctrl+-/Ctrl+0 can pick canvas zoom vs UI zoom.
+  ipcMain.on('editor:canvas-zoom-active', (event, active) => {
+    if (!trustedSender(event)) return;
+    canvasZoomActive = Boolean(active);
+  });
+
   const IMAGE_BUDGET = 256 * 1024 * 1024; // channels that carry base64 PNGs
   const h = (channel, fn, opts = {}) => {
     const { maxChars = 2 * 1024 * 1024, validate = null } = opts;
@@ -900,8 +1006,14 @@ function setupIpc() {
     platform: process.platform,
   }));
   // Platform capture-capability profile (session type, portal/PipeWire,
-  // xinput, click source, actionable messages) for the diagnostics UI.
-  h('platform:capabilities', () => require('./platform').detectCapabilities());
+  // xinput, click source, actionable messages) for the diagnostics UI, plus
+  // the honest active trigger for this machine and settings.
+  h('platform:capabilities', () => {
+    const platform = require('./platform');
+    const caps = platform.detectCapabilities();
+    const activeTrigger = platform.chooseCaptureTrigger(caps, settings.get('capture.fallbackTrigger') || 'interval');
+    return { ...caps, activeTrigger };
+  });
 }
 
 // ---- lifecycle --------------------------------------------------------------

app/platform/index.js

@@ -63,4 +63,19 @@ function detectCapabilities({ platform = process.platform, env = process.env } =
   };
 }
 
-module.exports = { detectPlatform, createWindowContextProvider, detectCapabilities };
+/**
+ * The honest capture-trigger decision for the current capabilities. On Linux
+ * this defers to the diagnostics helper (which never promises per-click
+ * capture with coordinates on Wayland); other platforms have a fixed answer.
+ */
+function chooseCaptureTrigger(capabilities, userTriggerPreference = 'interval') {
+  if (capabilities && capabilities.os === 'linux') {
+    return require('./linux/diagnostics').chooseCaptureTrigger(capabilities, userTriggerPreference);
+  }
+  if (capabilities && capabilities.os === 'windows') {
+    return { trigger: 'click', clickSource: 'windows-hook', coordinates: true, marker: true, note: '' };
+  }
+  return { trigger: 'click', clickSource: capabilities ? capabilities.os : 'unavailable', coordinates: true, marker: true, note: '' };
+}
+
+module.exports = { detectPlatform, createWindowContextProvider, detectCapabilities, chooseCaptureTrigger };

app/platform/linux/diagnostics.js

@@ -96,4 +96,61 @@ function detectLinuxCapabilities({
   };
 }
 
-module.exports = { detectLinuxCapabilities, detectSessionType };
+/**
+ * Decide the honest capture trigger for a Linux capability profile. StepForge
+ * must never *promise* per-click capture with coordinates on Wayland, because
+ * the platform does not expose pointer position to apps. Returns the trigger,
+ * whether clicks carry coordinates, whether a marker can be drawn, and a
+ * user-facing note. `userTriggerPreference` is the capture.fallbackTrigger
+ * setting ('interval' | 'hotkey') used only when no click source exists.
+ */
+function chooseCaptureTrigger(capabilities, userTriggerPreference = 'interval') {
+  const caps = capabilities || {};
+  const click = caps.clickCapture;
+
+  if (click === 'x11-xinput') {
+    return {
+      trigger: 'click',
+      clickSource: 'x11',
+      coordinates: true,
+      marker: true,
+      note: 'Per-click capture with an accurate marker (X11 + xinput).',
+    };
+  }
+  if (click === 'evdev-x11') {
+    return {
+      trigger: 'click',
+      clickSource: 'evdev-x11',
+      coordinates: true,
+      marker: true,
+      note: 'Per-click capture via kernel input devices (X11, no xinput).',
+    };
+  }
+  if (click === 'evdev-wayland') {
+    // Wayland exposes button presses (via evdev, if permitted) but NOT pointer
+    // position, so a step is captured per click but without a marker. This is
+    // only reached when the user opted into the least-privilege device rule.
+    return {
+      trigger: 'click',
+      clickSource: 'evdev-wayland',
+      coordinates: false,
+      marker: false,
+      note: 'Per-click capture on Wayland has no pointer position, so no marker is drawn.',
+    };
+  }
+
+  // No global click source: the safe baseline is the user's chosen fallback.
+  const trigger = userTriggerPreference === 'hotkey' ? 'hotkey' : 'interval';
+  return {
+    trigger,
+    clickSource: trigger,
+    coordinates: false,
+    marker: false,
+    note: caps.isWayland
+      ? 'Wayland does not expose global clicks; recording uses your ' + trigger + ' trigger. '
+        + 'Screen sharing is requested once per recording via the portal.'
+      : 'No global click source available; recording uses your ' + trigger + ' trigger.',
+  };
+}
+
+module.exports = { detectLinuxCapabilities, detectSessionType, chooseCaptureTrigger };

app/preload.js

@@ -67,6 +67,10 @@ const api = {
     onState: (fn) => ipcRenderer.on('capture:state', (e, payload) => fn(payload)),
     onStepUpdated: (fn) => ipcRenderer.on('step:updated', (e, payload) => fn(payload)),
   },
+  editor: {
+    onZoomShortcut: (fn) => ipcRenderer.on('editor:zoom-shortcut', (e, payload) => fn(payload)),
+    setCanvasZoomActive: (active) => ipcRenderer.send('editor:canvas-zoom-active', Boolean(active)),
+  },
   archive: {
     export: invoke('archive:export'),
     open: invoke('archive:open'),

app/renderer/dialogs.js

@@ -169,7 +169,14 @@ function makeHotkeyInput(value = '') {
   return wrap;
 }
 
-async function promptText({ title, label = 'Value', value = '', placeholder = '', multiline = false } = {}) {
+async function promptText({
+  title,
+  label = 'Value',
+  value = '',
+  placeholder = '',
+  multiline = false,
+  onInput = null,
+} = {}) {
   return new Promise((resolve) => {
     const field = multiline
       ? el('textarea', { rows: 6, placeholder }, value)
@@ -186,12 +193,20 @@ async function promptText({ title, label = 'Value', value = '', placeholder = ''
     });
 
     field.addEventListener('keydown', (e) => {
+      if (multiline && e.key === 'Enter') {
+        // Let the textarea keep the Enter key for a new line.
+        e.stopPropagation();
+        return;
+      }
       if (!multiline && e.key === 'Enter') {
         e.preventDefault();
         close();
         resolve(field.value);
       }
     });
+    field.addEventListener('input', () => {
+      if (typeof onInput === 'function') onInput(field.value);
+    });
 
     setTimeout(() => field.focus(), 0);
   });

app/renderer/editor.js

@@ -4,6 +4,7 @@
 
 const api = window.stepforge;
 const dialogs = window.StepForgeDialogs || {};
+const shortcuts = window.StepForgeShortcuts || {};
 
 const clone = (value) => JSON.parse(JSON.stringify(value));
 const BLOCK_KIND_ORDER = { text: 0, code: 1, table: 2 };
@@ -105,6 +106,24 @@ function isEditableTarget(target) {
   );
 }
 
+function zoomShortcutFromEvent(e) {
+  if (shortcuts.zoomShortcutFromKeyboardEvent) {
+    return shortcuts.zoomShortcutFromKeyboardEvent(e);
+  }
+
+  if (!(e.ctrlKey || e.metaKey)) return null;
+
+  const { key, code, shiftKey } = e;
+  if (key === '0' || code === 'Digit0' || code === 'Numpad0') return 'fit';
+  if (
+    key === '+' || key === '=' || key === 'Add' || key === 'Plus' ||
+    code === 'Equal' || code === 'NumpadAdd' ||
+    (key === '=' && shiftKey) || (code === 'Equal' && shiftKey)
+  ) return 'in';
+  if (key === '-' || key === '_' || key === 'Subtract' || key === 'Minus' || code === 'Minus' || code === 'NumpadSubtract') return 'out';
+  return null;
+}
+
 class GuideEditor {
   constructor({ root, onMetaChange = () => {}, onToast = toast, onBack = () => {} } = {}) {
     this.root = root;
@@ -141,6 +160,13 @@ class GuideEditor {
     this.saveStepDebounced = debounce(() => this.flushStep(), 180);
     this.saveGuideDebounced = debounce(() => this.flushGuide(), 180);
 
+    if (api.editor && typeof api.editor.onZoomShortcut === 'function') {
+      api.editor.onZoomShortcut((kind) => {
+        if (!this.active || !this.guide) return;
+        this.applyZoomShortcut(kind);
+      });
+    }
+
     this.onDocumentKeyDown = this.onDocumentKeyDown.bind(this);
     document.addEventListener('keydown', this.onDocumentKeyDown, true);
   }
@@ -152,6 +178,9 @@ class GuideEditor {
 
   setActive(active) {
     this.active = Boolean(active);
+    if (api.editor && typeof api.editor.setCanvasZoomActive === 'function') {
+      api.editor.setCanvasZoomActive(this.active);
+    }
     if (!this.active && this.guideId) {
       // Leaving the editor: flush pending debounced saves so navigation can
       // never drop the last edit (failures keep the dirty state and retry),
@@ -1182,7 +1211,6 @@ class GuideEditor {
     const typeSelect = makeSelect(selected.type, [
       'rect', 'oval', 'line', 'arrow', 'text', 'tooltip', 'number', 'blur', 'highlight', 'magnify', 'cursor',
     ].map((type) => ({ value: type, label: ANNOTATION_TYPE_LABELS[type] || type })));
-    const textInput = el('input', { type: 'text', value: selected.text || '', placeholder: 'Annotation text' });
     const valueInput = el('input', { type: 'number', value: Number.isFinite(selected.value) ? selected.value : '', placeholder: 'Value' });
     const strokeInput = el('input', { type: 'color', value: style.stroke || '#E5484D' });
     const fillInput = el('input', { type: 'color', value: style.fill && style.fill !== 'transparent' ? style.fill : '#ffffff' });
@@ -1218,9 +1246,17 @@ class GuideEditor {
     const fields = new Set(ANNOTATION_FIELDS[selected.type] || []);
     const strokeLabel = (selected.type === 'text' || selected.type === 'number') ? 'Color' : 'Stroke';
     const typeLabel = ANNOTATION_TYPE_LABELS[selected.type] || selected.type;
+    const textInput = fields.has('text')
+      ? el('textarea', {
+        rows: Math.max(3, Math.min(8, String(selected.text || '').split('\n').length)),
+        placeholder: 'Annotation text',
+        spellcheck: true,
+      })
+      : el('input', { type: 'text', value: selected.text || '', placeholder: 'Annotation text' });
+    if (fields.has('text')) textInput.value = selected.text || '';
 
     const rows = [labeledRow('Type', typeSelect)];
-    if (fields.has('text')) rows.push(labeledRow('Text', textInput));
+    if (fields.has('text')) rows.push(labeledRow('Text', textInput, { stacked: true }));
     if (fields.has('value')) rows.push(labeledRow('Value', valueInput));
     if (fields.has('stroke')) rows.push(labeledRow(strokeLabel, strokeInput));
     if (fields.has('fill')) rows.push(labeledRow('Fill', fillInput));
@@ -1348,6 +1384,22 @@ class GuideEditor {
     if (mode === 1.5) this.dom.zoom150Btn.classList.add('active');
   }
 
+  applyZoomShortcut(kind) {
+    if (kind === 'in') {
+      this.setZoom(Math.min(3, (Number(this.currentZoom) || 1) + 0.25));
+      return true;
+    }
+    if (kind === 'out') {
+      this.setZoom(Math.max(0.25, (Number(this.currentZoom) || 1) - 0.25));
+      return true;
+    }
+    if (kind === 'fit') {
+      this.setZoom('fit');
+      return true;
+    }
+    return false;
+  }
+
   pushCanvasHistory(recordOrLabel = 'change') {
     if (!this.currentStep) return;
     const record = recordOrLabel && typeof recordOrLabel === 'object'
@@ -2168,19 +2220,39 @@ class GuideEditor {
   async editAnnotationText(ann) {
     const step = this.currentStep;
     if (!step || !ann) return;
+    const originalText = ann.text ?? '';
+    const applyText = (nextText, { persist = true } = {}) => {
+      const selected = this.canvas.selected();
+      if (!selected) return;
+      selected.text = nextText;
+      step.annotations = clone(this.canvas.annotations || []);
+      this.pendingSave = true;
+      this.canvas.setAnnotations(step.annotations || []);
+      this.renderAnnotationPanel();
+      this.emitMeta();
+      if (persist) this.saveStepDebounced();
+    };
     const value = await dialogs.promptText({
       title: ann.type === 'tooltip' ? 'Edit tooltip' : 'Edit text',
       label: 'Text',
-      value: ann.text || '',
+      value: originalText,
       multiline: true,
+      onInput: applyText,
     });
-    if (value == null) return;
-    ann.text = value;
-    step.annotations = clone(step.annotations || []);
-    this.pendingSave = true;
+    this.saveStepDebounced.cancel();
+    if (value == null) {
+      const current = this.canvas.selected();
+      if ((current?.text ?? '') !== originalText) {
+        applyText(originalText, { persist: false });
+      }
+      await this.flushStep(step);
+      return;
+    }
+    const current = this.canvas.selected();
+    if ((current?.text ?? '') !== value) {
+      applyText(value, { persist: false });
+    }
     await this.flushStep(step);
-    this.renderAnnotationPanel();
-    this.emitMeta();
   }
 
   formatDescription(command, block = null) {
@@ -2227,6 +2299,12 @@ class GuideEditor {
 
   onDocumentKeyDown(e) {
     if (!this.active || !this.guide) return;
+    const zoomShortcut = zoomShortcutFromEvent(e);
+    if (zoomShortcut) {
+      e.preventDefault();
+      this.applyZoomShortcut(zoomShortcut);
+      return;
+    }
     if ((e.ctrlKey || e.metaKey) && e.key === '/' && !e.shiftKey) {
       e.preventDefault();
       this.openQuickActions();
@@ -2270,21 +2348,6 @@ class GuideEditor {
         if (next) this.selectStep(next.stepId);
         return;
       }
-      if ((e.ctrlKey || e.metaKey) && (e.key === '=' || e.key === '+')) {
-        e.preventDefault();
-        this.setZoom(Math.min(3, (Number(this.currentZoom) || 1) + 0.25));
-        return;
-      }
-      if ((e.ctrlKey || e.metaKey) && e.key === '-') {
-        e.preventDefault();
-        this.setZoom(Math.max(0.25, (Number(this.currentZoom) || 1) - 0.25));
-        return;
-      }
-      if ((e.ctrlKey || e.metaKey) && e.key === '0') {
-        e.preventDefault();
-        this.setZoom('fit');
-        return;
-      }
       // Copy / paste the selected annotation.
       if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === 'c' && this.selectedAnnotationId) {
         e.preventDefault();

app/renderer/index.html

@@ -21,6 +21,7 @@
 <div id="modal-root"></div>
 <div id="toast-root"></div>
 <script src="util.js"></script>
+<script src="../shortcut-utils.js"></script>
 <script src="canvas.js"></script>
 <script src="dialogs.js"></script>
 <script src="editor.js"></script>

app/shortcut-utils.js

@@ -0,0 +1,55 @@
+'use strict';
+
+(function attachShortcutUtils(root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = api;
+  }
+  if (root) {
+    root.StepForgeShortcuts = api;
+  }
+})(typeof globalThis !== 'undefined' ? globalThis : this, () => {
+  function hasZoomModifier(source) {
+    return Boolean(source && (source.ctrlKey || source.metaKey || source.control || source.meta));
+  }
+
+  function zoomShortcutFromSource(source) {
+    if (!hasZoomModifier(source)) return null;
+
+    const key = String(source.key || '');
+    const code = String(source.code || '');
+    const shiftKey = Boolean(source.shiftKey || source.shift);
+
+    if (key === '0' || code === 'Digit0' || code === 'Numpad0') return 'fit';
+
+    if (
+      key === '+' || key === '=' || key === 'Add' || key === 'Plus' ||
+      code === 'Equal' || code === 'NumpadAdd' ||
+      (key === '=' && shiftKey) || (code === 'Equal' && shiftKey)
+    ) {
+      return 'in';
+    }
+
+    if (
+      key === '-' || key === '_' || key === 'Subtract' || key === 'Minus' ||
+      code === 'Minus' || code === 'NumpadSubtract'
+    ) {
+      return 'out';
+    }
+
+    return null;
+  }
+
+  function zoomShortcutFromKeyboardEvent(event) {
+    return zoomShortcutFromSource(event);
+  }
+
+  function zoomShortcutFromInputEvent(input) {
+    return zoomShortcutFromSource(input);
+  }
+
+  return {
+    zoomShortcutFromInputEvent,
+    zoomShortcutFromKeyboardEvent,
+  };
+});

docs/GETTING_STARTED_WITH_LINUX.md

@@ -13,10 +13,11 @@ difference, how to get the best experience, and how to enable per-click capture.
 
 | | **X11 / "Ubuntu on Xorg"** | **Wayland (default on Ubuntu)** |
 |---|---|---|
-| Screenshot per click | ✅ Yes | ✅ Yes (needs `input` group) |
+| Screenshot per click | ✅ Yes | ⚙️ Optional (least-privilege mouse rule) |
 | Red circle on the click | ✅ Yes | ❌ No (Wayland hides the cursor position) |
 | "Share your screen" prompt | Never | Once per recording session |
-| Setup needed | None | Add yourself to the `input` group |
+| Default trigger | Per click | Global hotkey or timed interval |
+| Setup needed | None | None (per-click is opt-in, mice only) |
 
 **If you want the full Windows-like experience (click capture *with* the red
 marker), use an Xorg session — see [Option A](#option-a-best-experience--use-xorg).**
@@ -67,27 +68,30 @@ stream stays open until you stop recording.
 > If you never see steps appear, make sure you actually picked a screen and
 > clicked **Share** in that dialog.
 
-### Per-click capture (requires the `input` group)
+### Per-click capture (optional, least-privilege)
 
-By default on Wayland, StepForge cannot see your clicks, so it falls back to
-**capturing a screenshot every few seconds** (timed capture).
+By default on Wayland, StepForge cannot see your clicks, so it uses a **global
+hotkey or a timed interval** to capture (see below). This is the recommended,
+no-extra-permissions path.
 
-To get a screenshot **on every click** instead, give your user read access to
-the mouse devices by joining the `input` group:
+If you want a screenshot **on every click**, you can grant StepForge read
+access to your **mouse** devices. Do **not** use `sudo usermod -aG input`:
+joining the `input` group grants your user access to *all* input devices —
+**including keyboards** — permanently, on every session. That is a keylogging
+surface StepForge does not need.
+
+Instead, install the least-privilege udev rule, which grants your active
+session read access to **mouse devices only** (never keyboards), scoped to
+whoever is physically logged in:
 
 ```bash
-sudo usermod -aG input "$USER"
+bash scripts/linux/enable-click-capture.sh
 ```
 
-Then **log out and log back in** (group membership only applies to new sessions).
-Verify it took effect:
-
-```bash
-groups | tr ' ' '\n' | grep input    # should print: input
-```
-
-Now StepForge reads mouse buttons directly from the kernel (`/dev/input`) and
-captures a screenshot on each click.
+It shows you the exact rule and asks for confirmation before installing. Under
+the hood it uses a systemd `uaccess` ACL restricted to `ID_INPUT_MOUSE`
+devices — see [packaging/linux/common/60-stepforge-input.rules](../packaging/linux/common/60-stepforge-input.rules).
+Re-log in (or replug a USB mouse) for it to apply.
 
 > **No red marker on Wayland.** Even with per-click capture working, Wayland
 > does not tell apps *where* the pointer is, so StepForge cannot draw the circle
@@ -114,10 +118,16 @@ On launch StepForge chooses the best available click source:
 1. **Windows** — low-level mouse hook (position + timing).
 2. **X11** — `xinput` (position + timing → full red marker).
 3. **Linux evdev** (`/dev/input`) — button presses on X11 *and* Wayland, no
-   position on Wayland. Used when `xinput` can't see clicks (i.e. Wayland), if
-   you're in the `input` group.
-4. **Timed capture** — the always-works fallback (a screenshot every N seconds)
-   when no click source is available.
+   position on Wayland. Used when `xinput` can't see clicks (i.e. Wayland) and
+   only if you opted into the least-privilege mouse rule
+   (`scripts/linux/enable-click-capture.sh`).
+4. **Hotkey / timed capture** — the always-works fallback (the Capture hotkey,
+   or a screenshot every N seconds) when no click source is available. On
+   Wayland this is the default, and StepForge reports it honestly instead of
+   pretending clicks are captured.
+
+Open **Settings → Diagnostics** to see the detected session type, portal/
+PipeWire status, and the active capture trigger for your machine.
 
 Screen frames come from a single long-lived capture stream per recording, so
 clicks/timer ticks never re-open the screen-share dialog.
@@ -149,7 +159,9 @@ STEPFORGE_CAPTURE_LOG=1 npm start
 
 - `[stepforge] screen-capture stream active …` — the stream is up.
 - `[stepforge] per-click capture via evdev on N device(s) …` — clicks are wired up.
-- `[stepforge] no readable mouse input devices …` — you need the `input` group (see above).
+- `[stepforge] no readable mouse input devices …` — per-click capture is not
+  enabled; run `scripts/linux/enable-click-capture.sh` for the least-privilege
+  mouse rule, or just use the hotkey/interval trigger.
 
 **Harmless console noise.** Lines like `vaInitialize failed`, `Frame latency is
 negative`, and `StatusNotifierItem … already exported` come from Chromium/GNOME,

packaging/linux/common/60-stepforge-input.rules

@@ -0,0 +1,19 @@
+# StepForge least-privilege input access (OPTIONAL, opt-in).
+#
+# Grants the user at the ACTIVE local session read/write access to MOUSE input
+# devices only, via systemd-logind's `uaccess` ACL. This is the least-privilege
+# alternative to joining the broad `input` group, which would grant access to
+# ALL input devices — including keyboards — for the user permanently, on every
+# session. StepForge never needs keystrokes, so this rule deliberately EXCLUDES
+# keyboards.
+#
+# Scope of what this grants:
+#   * only devices udev classifies as a mouse (ID_INPUT_MOUSE=1),
+#   * only when they are NOT also a keyboard (ID_INPUT_KEYBOARD!=1),
+#   * only to whoever is logged in at the physical seat (uaccess is
+#     session-scoped, not a permanent group membership).
+#
+# StepForge uses this only for the optional Wayland per-click *trigger* (button
+# presses, no coordinates). It is not required — the safe default is a global
+# hotkey or interval capture.
+SUBSYSTEM=="input", KERNEL=="event*", ENV{ID_INPUT_MOUSE}=="1", ENV{ID_INPUT_KEYBOARD}!="1", TAG+="uaccess"

scripts/linux/enable-click-capture.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# OPTIONAL: enable per-click capture on Wayland (or X11 without xinput) using a
+# LEAST-PRIVILEGE udev rule instead of the broad `input` group.
+#
+# Security tradeoff (read before running):
+#   * This grants your ACTIVE local session read access to MOUSE devices only.
+#   * It deliberately EXCLUDES keyboards — StepForge never needs keystrokes.
+#   * Access is session-scoped (systemd `uaccess` ACL), not a permanent group.
+#   * It is NOT required: the safe default is a global hotkey or interval
+#     capture. Only enable this if you want a screenshot on every click.
+#
+# Compare to `sudo usermod -aG input "$USER"`, which grants access to ALL input
+# devices (including keyboards) for your user on every session — a much larger
+# surface. This script does not do that.
+set -euo pipefail
+
+RULE_SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/packaging/linux/common/60-stepforge-input.rules"
+RULE_DEST="/etc/udev/rules.d/60-stepforge-input.rules"
+
+if [ ! -f "$RULE_SRC" ]; then
+  echo "error: rule file not found at $RULE_SRC" >&2
+  exit 1
+fi
+
+echo "This installs a least-privilege udev rule granting your session read"
+echo "access to MOUSE devices only (never keyboards):"
+echo
+sed 's/^/    /' "$RULE_SRC"
+echo
+printf 'Install it to %s? [y/N] ' "$RULE_DEST"
+read -r reply
+case "$reply" in
+  y|Y|yes|YES) ;;
+  *) echo "Aborted. No changes made."; exit 0 ;;
+esac
+
+SUDO=""
+if [ "$(id -u)" -ne 0 ]; then SUDO="sudo"; fi
+
+$SUDO install -m 0644 "$RULE_SRC" "$RULE_DEST"
+$SUDO udevadm control --reload-rules
+$SUDO udevadm trigger --subsystem-match=input --action=change || true
+
+cat <<'MSG'
+
+Installed. You may need to unplug/replug a USB mouse or re-log in for the ACL
+to apply to already-connected devices.
+
+To remove it later:
+  sudo rm /etc/udev/rules.d/60-stepforge-input.rules
+  sudo udevadm control --reload-rules
+MSG

tests/unit/packaging-linux.test.js

@@ -6,7 +6,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const ROOT = path.resolve(__dirname, '..', '..');
-const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
+// Strip CR so /^...$/m assertions are robust to CRLF checkouts on Windows CI.
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8').replace(/\r\n/g, '\n');
 const exists = (rel) => fs.existsSync(path.join(ROOT, rel));
 
 // These are structural checks that run in the normal (cross-platform) unit

tests/unit/shortcut-utils.test.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  zoomShortcutFromInputEvent,
+  zoomShortcutFromKeyboardEvent,
+} = require('../../app/shortcut-utils');
+
+test('zoom shortcut helper recognizes zoom in, out, and fit across event shapes', () => {
+  assert.equal(zoomShortcutFromKeyboardEvent({ ctrlKey: true, key: '=', code: 'Equal' }), 'in');
+  assert.equal(zoomShortcutFromKeyboardEvent({ ctrlKey: true, key: '+', code: 'NumpadAdd' }), 'in');
+  assert.equal(zoomShortcutFromKeyboardEvent({ ctrlKey: true, key: 'Plus', code: 'Equal' }), 'in');
+  assert.equal(zoomShortcutFromKeyboardEvent({ ctrlKey: true, key: '-', code: 'Minus' }), 'out');
+  assert.equal(zoomShortcutFromKeyboardEvent({ metaKey: true, key: '0', code: 'Digit0' }), 'fit');
+  assert.equal(zoomShortcutFromKeyboardEvent({ ctrlKey: true, key: '=', code: 'Equal', shiftKey: true }), 'in');
+});
+
+test('zoom shortcut helper recognizes Electron before-input-event payloads', () => {
+  assert.equal(zoomShortcutFromInputEvent({ control: true, key: '=', code: 'Equal' }), 'in');
+  assert.equal(zoomShortcutFromInputEvent({ control: true, key: '=', code: 'Equal', shift: true }), 'in');
+  assert.equal(zoomShortcutFromInputEvent({ control: true, key: 'Plus', code: 'Equal', shift: true }), 'in');
+  assert.equal(zoomShortcutFromInputEvent({ control: true, key: '-', code: 'Minus' }), 'out');
+  assert.equal(zoomShortcutFromInputEvent({ meta: true, key: '0', code: 'Digit0' }), 'fit');
+});

tests/unit/wayland-honesty.test.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { chooseCaptureTrigger, detectLinuxCapabilities } = require('../../app/platform/linux/diagnostics');
+const platform = require('../../app/platform');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+// Strip CR so assertions are robust to CRLF checkouts on Windows CI.
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8').replace(/\r\n/g, '\n');
+const exists = (rel) => fs.existsSync(path.join(ROOT, rel));
+
+// ---- honest trigger decisions ----------------------------------------------
+
+test('X11 + xinput promises per-click capture with a marker', () => {
+  const t = chooseCaptureTrigger({ os: 'linux', isWayland: false, clickCapture: 'x11-xinput' });
+  assert.equal(t.trigger, 'click');
+  assert.equal(t.coordinates, true);
+  assert.equal(t.marker, true);
+});
+
+test('Wayland evdev captures per click but never promises coordinates or a marker', () => {
+  const t = chooseCaptureTrigger({ os: 'linux', isWayland: true, clickCapture: 'evdev-wayland' });
+  assert.equal(t.trigger, 'click');
+  assert.equal(t.coordinates, false, 'Wayland exposes no pointer position');
+  assert.equal(t.marker, false);
+});
+
+test('Wayland without a click source falls back to the user trigger, honestly', () => {
+  const interval = chooseCaptureTrigger({ os: 'linux', isWayland: true, clickCapture: 'hotkey-or-interval-only' }, 'interval');
+  assert.equal(interval.trigger, 'interval');
+  assert.equal(interval.coordinates, false);
+  assert.match(interval.note, /Wayland does not expose global clicks/i);
+
+  const hotkey = chooseCaptureTrigger({ os: 'linux', isWayland: true, clickCapture: 'hotkey-or-interval-only' }, 'hotkey');
+  assert.equal(hotkey.trigger, 'hotkey');
+});
+
+test('the platform facade wires the Linux trigger decision from real capabilities', () => {
+  const caps = detectLinuxCapabilities({
+    env: { XDG_SESSION_TYPE: 'wayland', WAYLAND_DISPLAY: 'wayland-0' },
+    hasBinary: () => false,
+    existsSync: () => false,
+    readdirSync: () => [],
+  });
+  const t = platform.chooseCaptureTrigger(caps, 'interval');
+  assert.equal(t.trigger, 'interval');
+  assert.equal(t.marker, false);
+});
+
+test('Windows always reports per-click capture', () => {
+  const t = platform.chooseCaptureTrigger({ os: 'windows' });
+  assert.equal(t.trigger, 'click');
+  assert.equal(t.coordinates, true);
+});
+
+// ---- least-privilege input access -------------------------------------------
+
+test('the udev rule grants mouse-only access and excludes keyboards', () => {
+  assert.ok(exists('packaging/linux/common/60-stepforge-input.rules'));
+  const rule = read('packaging/linux/common/60-stepforge-input.rules');
+  assert.match(rule, /ID_INPUT_MOUSE\}=="1"/);
+  assert.match(rule, /ID_INPUT_KEYBOARD\}!="1"/, 'must exclude keyboards');
+  assert.match(rule, /TAG\+="uaccess"/, 'session-scoped ACL, not a permanent group');
+});
+
+test('the enable script is opt-in and installs the least-privilege rule, not the input group', () => {
+  assert.ok(exists('scripts/linux/enable-click-capture.sh'));
+  const script = read('scripts/linux/enable-click-capture.sh');
+  assert.match(script, /read -r reply/, 'must confirm before installing');
+  assert.match(script, /60-stepforge-input\.rules/, 'installs the least-privilege udev rule');
+  // usermod may only appear in a comment (warning), never as an executed
+  // command. Check command position (line start, optional sudo) so this is
+  // robust to CRLF vs LF line endings across platforms.
+  assert.doesNotMatch(script, /^\s*(sudo\s+)?usermod\b/m, 'must not run the broad input-group command');
+});
+
+// ---- docs no longer push the broad input group ------------------------------
+
+test('Linux docs recommend the least-privilege path and warn against the input group', () => {
+  const doc = read('docs/GETTING_STARTED_WITH_LINUX.md');
+  assert.match(doc, /enable-click-capture\.sh/);
+  assert.match(doc, /least-privilege/i);
+  // The broad group is now presented as a warning ("Do not use ..."), not a
+  // recommended step.
+  assert.match(doc, /Do \*\*not\*\* use `sudo usermod/);
+});