Installation & Keyboard Shortcuts

Kalc is a universal macOS desktop application built exclusively using native Apple system frameworks (AppKit, TextKit 2, Carbon, Network, and JavaScriptCore).

---

System Requirements

• Operating System: macOS 14.0 (Sonoma), macOS 15.0 (Sequoia), or newer.
• Hardware Architecture: Universal binary with native execution for both Apple Silicon (arm64, M1/M2/M3/M4/M5) and Intel (x86_64).
• Dependencies: Zero external package dependencies. No Node.js, Bun, Python, or Homebrew packages required.

---

Installation Steps

Direct Download (.dmg / .zip)

1. Download the latest Kalc.app release from the official repository or release page.
2. Open the downloaded disk image (Kalc.dmg) or unpack the archive.
3. Drag Kalc.app into your /Applications directory.
4. Launch Kalc from Launchpad, Spotlight, or the Application folder.

First Launch & macOS Gatekeeper Security Notice

Kalc is an open-source project and is currently ad-hoc signed while awaiting Apple Developer ID notarization. On macOS Sonoma and Sequoia, macOS Gatekeeper may display a security alert on first launch:

“Kalc.app” Not Opened
Apple could not verify “Kalc.app” is free of malware that may harm your Mac or compromise your privacy.

If you encounter this prompt, remove the quarantine attribute via Terminal:

xattr -cr /Applications/Kalc.app

GUI Alternative:

1. In Finder, open /Applications.
2. Right-click (or Control-click) Kalc.app and select Open.
3. Click Open in the confirmation dialog.

Accessibility Permissions

If you choose to enable global background hotkey triggers:

• Open System Settings > Privacy & Security > Accessibility.
• Ensure Kalc is toggled on to allow system-wide hotkeys (such as ⌥ Space to summon the quick popover).

---

Workspace Modes

1. Main Desktop Window

The standard two-column editor window featuring:

• Dual-Mode Header: A streamlined centered title with a new tab button when 1 tab is open, transitioning to a full scrollable tab bar with thin scrollers when multiple tabs exist.
• Synchronized Results Gutter: Line-by-line evaluated results pinned alongside your text with 1:1 baseline synchronization and a 600ms ease-out flash animation.
• Bottom Status Bar: Toggleable compact footer displaying recalculation latency (⚡ 0.8ms eval), precision indicator, currency capsule switcher, and the Command Palette launcher.

2. Menu-Bar Quick Popover

Click the Kalc menu-bar icon (or press the global hotkey) to summon a lightweight scratchpad popover.

• Write fast one-off calculations without switching away from your current workspace.
• Press Esc to dismiss the popover without losing your scratchpad buffer.
• Click the Expand button in the top-right corner to seamlessly transfer your scratchpad text to the main desktop window.

---

Comprehensive Keyboard Shortcuts

Command / Action	Shortcut	Scope & Behavior
Toggle Quick Popover	⌥ Space (Configurable)	Global system-wide shortcut toggling the menu-bar popover from any app.
Command Palette	⌘ K	Centered floating modal for actions, conversions, theme switching, and settings.
Formula Templates	⇧ ⌘ T	Opens the template browser panel with split live preview.
New Document Tab	⌘ T	Appends a new scratchpad tab to the active window.
Close Document Tab	⌘ W	Closes the active tab (retains a clean scratchpad if last tab).
Select Tab 1 ... 9	⌘ 1 ... ⌘ 9	Instantly switches to the tab at specified index.
Next / Previous Tab	⇧ ⌘ ] / ⇧ ⌘ [	Cycles sequentially through open tabs.
Number Scrubbing	⌥ + Drag Number	Hold Option and drag mouse horizontally across any number to tweak its value live.
Go to Declaration	⌘-Click on Variable	Jumps the cursor to the definition line of that variable (across local or foreign tabs).
Documentation HUD	Hover over symbol	Displays a floating obsidian HUD with function signatures, parameter docs, or live values.
Cross-Tab Variable Trigger	@	Opens autocomplete popup listing all variables from other open workspace sheets.
Wrap in Parentheses	⇧ ⌘ 0	Encloses active text selection in ( and ).
Copy Active Line Result	⇧ ⌘ C	Copies the current line's evaluated gutter result to the clipboard.
Copy Document & Results	⌥ ⌘ C	Copies the full source text with right-aligned gutter outputs.
Clear Document	⌥ ⌘ ⌫	Clears all text in the active tab (supports atomic Undo ⌘ Z).
Capture Screenshot	⇧ ⌘ S	Captures high-DPI Retina card of active tab to clipboard (zero buttons, gradient backdrop).
Save Screenshot As...	⌥ ⇧ ⌘ S	Renders high-DPI screenshot and prompts native macOS Save Dialog for PNG export.
Format / Beautify Document	⌥ ⇧ ⌘ F	Runs AST FormulaFormatter across active document.
Open File	⌘ O	Native open panel for .kalc and plain-text files.
Save / Export	⌘ S	Writes document buffer to .kalc plain-text file.
Print Document	⌘ P	Native macOS print layout for formatted text + gutter.
Settings Preferences	⌘ ,	Opens the 6-tab application preferences window.

---

Preference Settings (⌘ ,)

The Kalc Preferences window is organized into seven tabs:

1. General: Launch at login, restore previous multi-tab sessions, confirm tab closures, auto-copy result on gutter click, and menu-bar icon click actions.
2. Editor: Typography selection (JetBrains Mono, SF Mono, Menlo, Geist Mono, Courier New), font size, baseline rhythm (Compact 20pt, Standard 24pt, Relaxed 28pt, Spacious 32pt), Obsidian Kinetic theme picker, active line highlight, and dependency highlighting.
3. Calculations: Angle mode (Degrees vs. Radians), decimal precision (0 to 12 places), decimal separator (dot, comma, system), grouping separator (comma, dot, space, apostrophe), currency symbol position ($10 vs 10$), and default currency.
4. Shortcuts: Hotkey recorder for global summoning (⌥ Space), menu popover toggle, and shortcut customizations.
5. Rates & Daemon: Automatic currency exchange rate background refresh interval, offline cache status, local HTTP daemon toggle (127.0.0.1:15055), and port assignment.
6. Plugins: Installed JavaScript extensions list, version/author metadata, enable/disable switches, drag-and-drop installer for .kalcplugin packages, and one-click "Open Plugins Folder" button.
7. Screenshot: Configure tab title inclusion, decorative macOS window controls, fit-to-content vertical framing, gradient backdrop themes (Obsidian Midnight, Sunset Glow, Mint Aurora, Oceanic Azure, Titanium Graphite, Northern Lights), padding presets (16pt to 64pt), default capture destination (Save As vs. Clipboard), and real-time live preview.