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.