Editor Mechanics & Code Intelligence

Kalc is built on Apple's TextKit 2 layout engine, offering fluid interactions, typography rhythms, and IDE-grade code intelligence on a notepad surface.

---

1. Line Classification Hierarchy

Before an expression is tokenized or parsed, LineClassifier evaluates each line according to a strict, mutually exclusive priority order:

graph TD
    A[Raw Line Text] --> B{Empty or Spaces?}
    B -- Yes --> C[Blank Line: Resets aggregate blocks]
    B -- No --> D{Starts with # heading?}
    D -- Yes --> E[Markdown Heading: Resets aggregates, Amber styled]
    D -- No --> F{Starts with // or #?}
    F -- Yes --> G[Comment Line: Preserves aggregates, Muted Slate]
    F -- No --> H{Wrapped in quotes?}
    H -- Yes --> I[Quoted Annotation: Suppressed from calculation]
    H -- No --> J{Contains Label: expr?}
    J -- Yes --> K[Label Declaration: Named line result]
    J -- No --> L{Matches var = expr?}
    L -- Yes --> M[Variable Binding: Exports to Scope]
    L -- No --> N[Pure Expression: Math, units, currency, dates]

1. Blank Lines

Lines containing only whitespace or zero characters.

• Behavior: Resets local contextual aggregate blocks (sum, avg, subtotal). Emits no gutter result.

2. Markdown Headings (#, ##, ###)

Lines starting with one to six # symbols followed by a space.

• Behavior: Organizes documents into clear sections, resets aggregate accumulators, and renders in Obsidian Amber (#FBBF24).

3. Comments (// or #)

Lines whose first non-whitespace characters are // or a hash # not followed by heading whitespace.

• Behavior: Allows notes and annotations without breaking aggregate continuity or emitting gutter numbers. Rendered in Muted Slate (#71788E).

4. Quoted Annotations

Text enclosed in quotation marks ("..." or '...').

• Behavior: Quotes allow inline descriptions. Unclosed quotation marks emit an informative inline diagnostic.

5. Label Declarations (Name: expr)

Labels formatted as Identifier: followed by an expression.

• Behavior: Labels are automatically disambiguated from clock timestamps (2:30 pm) and URLs (https://...). The label appears in autocomplete and reports cleanly in copy-all exports.

6. Variable Bindings (name = expr)

Binds an alphanumeric identifier to the evaluated expression in the document's Scope.

• Behavior: The variable becomes immediately accessible to all subsequent lines in the document (and across tabs via Tab@name).

7. Pure Expressions

Any standard mathematical equation, dimensional conversion, currency transaction, or date arithmetic.

---

2. Variables & Scoping

Variable names must begin with a letter or underscore, followed by letters, numbers, or underscores:

base_salary = $120,000
bonus_pct = 15%
total_compensation = base_salary + bonus_pct on base_salary  // $138,000.00

Sequential Scoping & Forward References

Kalc enforces sequential top-to-bottom evaluation. Referencing a variable before its declaration line emits a clear diagnostic (Variable 'x' used before declaration), preventing circular logic and hidden state.

---

3. Contextual Referencing

prev

The keyword prev resolves to the evaluated scalar, unit, or currency value of the closest preceding evaluated line. It automatically skips over comments, headings, and blank lines:

$150.00                                         // $150.00
// Add dinner tip
prev + 20%                                      // $180.00

Operator-Starting Lines

If you begin a line with an operator (+, -, *, /, ^, in, to), Kalc automatically prefixes prev:

1,000 EUR in USD                                // $1,085.00
+ 10% tax                                       // $1,193.50
- $50 discount                                  // $1,143.50
/ 2                                             // $571.75

Explicit Line References (lineN)

You can reference any 1-based line number directly:

line1 = $450                                    // $450.00
line2 = $850                                    // $850.00
line3 = line1 + line2                           // $1,300.00

---

4. Block Aggregates & Empty Semantics

Kalc features upward-scanning aggregates that summarize blocks without requiring you to manually highlight rows or type ranges:

Flight: $650                                    // $650.00
Hotel:  $820                                    // $820.00
Taxi:   $90                                     // $90.00
sum                                             // $1,560.00
avg                                             // $520.00

Aggregate Behavior Rules

• sum / total: Accumulates all dimensionally compatible numeric lines upward until hitting a blank line, heading, or file boundary. If an aggregate block has zero preceding numeric lines, sum evaluates to 0.
• avg / average: Calculates the arithmetic mean. If called on an empty block, it emits an informative diagnostic: "Empty block: no values to average".
• subtotal: Accumulates values within the current section and resets the local section counter.
• grand total: Computes the sum of all preceding subtotal lines throughout the active document.
• #tag total / #tag avg: Scans across the document collecting all lines annotated with an inline hashtag (e.g. #tax total or #groceries avg).

---

5. Interactive Number Scrubbing

Holding the Option (⌥) key and dragging your mouse horizontally over any numeric literal dynamically adjusts the value in real time:

• Drag Right: Increments the value smoothly.
• Drag Left: Decrements the value smoothly.
• Live Gutter Refresh: As you scrub, dependent calculations throughout the document (and across connected tabs) recalculate instantly within the 8.0 ms frame budget.
• Atomic Undo (⌘ Z): Scrubbing registers an atomic single-step undo transaction. Pressing ⌘ Z restores the exact pre-scrub number.

---

6. Code Intelligence & Navigation

Go to Declaration (⌘-Click)

When hovering over any variable name or cross-tab reference (Tab1@rate) while holding the Command (⌘) key:

1. The mouse cursor changes to a pointing hand.
2. The referenced variable underlines in electric mint.
3. Clicking immediately jumps your cursor to the declaration line of that variable—even if it is defined inside another tab in your workspace.

Documentation Hover HUD

Hovering your mouse over any built-in function or plugin extension opens a floating obsidian HUD panel showing:

• Parameter signatures and return types.
• Category badges (FUNCTION, PLUGIN).
• Detailed descriptions and parameter lists.
• Copyable, verified syntax examples.

Hovering over a variable shows its live evaluated value and origin sheet.

Autocomplete & Suggestion Popup

Typing alphanumeric characters automatically activates fuzzy autocompletion:

• Searches across math functions, units, currency symbols, and document variables.
• Typing @ specifically triggers cross-tab discovery, displaying all available exported variables across your workspace.
• Press Tab or Return to insert the selected suggestion. Press Esc to dismiss.

Dependency Highlighting

When your cursor rests on a variable, Kalc automatically illuminates:

1. The Source: The upstream declaration line.
2. The Impact: All downstream expressions and totals depending on that variable.

---

7. Fault Isolation

User editing should never break the entire notepad. If a typo or incompatible unit conversion occurs on line $N$, Kalc isolates the error strictly to line $N$:

radius = 10 meters                              // 10 m
faulty = 50 kg in meters                        // ⚠️ Cannot convert mass (kg) to length (meter)
area = pi * radius^2                            // 314.16 m2

Line $N+1$ continues evaluating with complete precision. Error diagnostics display in muted coral with hover explanations describing the root cause.

---

8. Formula Syntax Assistant ([Tab] to Insert)

When typing conversational word problems, informal discounts, or multi-step logic (e.g. 5 shirts at $25 each minus 10% coupon), Kalc's optional Formula Syntax Assistant detects natural phrasing and renders an interactive suggestion chip directly in the results gutter:

Editor (Line 3):  5 shirts at $25 each minus 10% coupon
Result Gutter:    Suggestion: 5 * $25 - 10%  (⇒ $112.50)  [Insert]

Editor Interaction Rules:

• One-Key Insertion: Press Tab or click [Insert] to instantly replace the line with canonical Kalc syntax.
• Atomic Undo (⌘ Z): The replacement is registered as an atomic action in NSUndoManager. Pressing ⌘ Z immediately restores your original words.
• Decoupled Cursor: Pressing Enter moves your cursor to line $N+1$ while preserving the suggestion chip on line $N$, allowing you to continue typing or accept the proposal from line $N+1$.
• Clean Dismissal: Pressing Esc, moving your cursor within the line, or typing additional characters cleanly dismisses the chip.
• Safe Preview Gate: For suggestions calling JavaScript plugins, live dry-run evaluation is deferred (isDeferredExecution = true) until you explicitly insert the line, preventing untrusted scripts from running while you type.

---

9. High-Fidelity Screenshot Studio (⇧ ⌘ S / ⌥ ⇧ ⌘ S)

Kalc includes a native, offscreen high-DPI Retina rendering engine designed for sharing crystal-clear snippets of your calculations across Slack, Twitter, Discord, and documentation.

Key Visual Properties

1. Zero-Button Invariant: Screenshots strictly exclude all interactive window chrome and controls:

   • No window close/minimize/zoom buttons (replaced by optional decorative non-interactive dots).
   • No header buttons (Settings gear, Formula Templates stack, New Tab +, Update Available badges).
   • No tab close x buttons.
   • No bottom status bar buttons or toolbar controls.
   • Insertion caret blinking and selection rectangles are automatically suppressed during capture.

2. Intelligent Content Framing (fitToContent): Rather than capturing arbitrary empty viewport space, Kalc calculates the exact vertical extent of your expressions and gutter results, framing the card tightly around your thoughts with comfortable breathing margins.

3. Padded Gradient Backdrops: Renders your calculation card over a soft-cornered (10 pt radius) ambient drop shadow against curated gradient themes:

   • Obsidian Midnight: Kalc signature deep navy/slate brand gradient (#0B0F19 $\rightarrow$ #161F30 $\rightarrow$ #0E1422).
   • Sunset Glow: Warm sunset palette (#2E0854 $\rightarrow$ #C02662 $\rightarrow$ #FB923C).
   • Mint Aurora: Emerald to neon mint (#022C22 $\rightarrow$ #0F766E $\rightarrow$ #10B981).
   • Oceanic Azure: Deep navy to vibrant cobalt (#030712 $\rightarrow$ #1E1B4B $\rightarrow$ #2563EB).
   • Titanium Graphite: Modern matte charcoal (#18181B $\rightarrow$ #27272A $\rightarrow$ #3F3F46).
   • Northern Lights: Emerald, cyan, and violet spectrum (#0F172A $\rightarrow$ #059669 $\rightarrow$ #06B6D4 $\rightarrow$ #8B5CF6).

4. Multi-Tab Title Bar Logic:

   • When Include Tab Titles is checked and multiple tabs exist, clean tab pills appear at the top.
   • When disabled or on a single tab, the title bar is completely omitted (or cleanly displays only decorative window dots if enabled).

Shortcuts & Export

• ⇧ ⌘ S: Capture screenshot directly to the macOS clipboard with haptic feedback and a visual confirmation toast.
• ⌥ ⇧ ⌘ S: Opens the native macOS Save Dialog to export a 2x Retina PNG file directly.
• Menu Bar: Accessible under File $\rightarrow$ Capture Screenshot and Save Screenshot As....
• Settings: Customize backdrop themes, padding, and defaults under Preferences (⌘ ,) $\rightarrow$ Screenshot.