feat: Add write to top of file switch for capture to active file (#248)

[chhoumann]

Description

This PR adds a new option to insert capture content at the top of the active file (after frontmatter) instead of at the cursor position, addressing the feature request in #248.

Changes

• Added new activeFileTop capture action type
• Added activeFileWritePosition field to capture choice types ("cursor" | "top")
• Updated UI to show separate options:
  • "At cursor" (default) - inserts at current cursor position
  • "Top of file (after frontmatter)" - inserts at top of file after frontmatter
• Updated engine and formatter logic to handle the new action
• Added comprehensive tests for the new functionality
• Ensured backward compatibility for existing choices (defaults to "cursor")

Testing

• ✅ All existing tests pass
• ✅ Added 3 new tests for the activeFileTop action
• ✅ Verified backward compatibility with existing choices
• ✅ No linting errors

Related Issue

Closes #248

Summary by CodeRabbit

Release Notes

• New Features
  • Added support for capturing content to the top of your active file (after frontmatter).
  • Introduced new write position option for active file captures: select between cursor position or top of file.
  • Enhanced content templating to apply when writing to the top of a file.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
quickadd	Ready	Preview	Nov 14, 2025 4:08pm

[coderabbitai]

Walkthrough

This PR adds a "write to top of file" feature by introducing a new capture action type "activeFileTop" and a configurable activeFileWritePosition property. The changes enable users to specify whether captures should be inserted at the active cursor location or at the top of the file.

Changes

Cohort / File(s)	Summary
Type definitions and interfaces src/types/choices/ICaptureChoice.ts, src/types/choices/CaptureChoice.ts, src/engine/captureAction.ts	Added optional activeFileWritePosition property ("cursor" | "top") to capture choice interfaces and class; extended CaptureAction type to include new "activeFileTop" variant.
Capture action logic src/engine/captureAction.ts, src/engine/CaptureChoiceEngine.ts	Modified getCaptureAction() to return "activeFileTop" when writing to top of active file; added isEditorInsertionAction computed property to consolidate editor-insertion action checks.
Content formatting and templating src/formatters/captureChoiceFormatter.ts	Extended shouldRunTemplater condition to trigger templating when activeFileWritePosition equals "top".
UI builder src/gui/ChoiceBuilder/captureChoiceBuilder.ts	Added "Top of file (after frontmatter)" dropdown option, initialized activeFileWritePosition default to "cursor", and wired UI selection to set property value.
Tests src/engine/captureAction.test.ts	Added test coverage for new activeFileWritePosition property, verifying "top" and "cursor" behaviors and action prioritization.

Sequence Diagram

sequenceDiagram
    participant User
    participant Builder as Choice Builder
    participant Engine as Capture Engine
    participant Action as Action Resolver
    participant Formatter as Content Formatter

    User->>Builder: Select "Top of file" option
    Builder->>Builder: Set activeFileWritePosition = "top"
    
    User->>Engine: Trigger capture
    Engine->>Action: getCaptureAction(choice)
    
    alt activeFileWritePosition = "top"
        Action->>Action: Check: captureToActiveFile && !prepend<br/>&& !insertAfter.enabled
        Action-->>Engine: return "activeFileTop"
    else activeFileWritePosition = "cursor"
        Action-->>Engine: return "currentLine" or other
    end
    
    Engine->>Formatter: shouldRunTemplater(action)
    alt action = "activeFileTop"
        Formatter->>Formatter: Trigger templating
    end
    
    Engine->>Engine: Insert content at top<br/>with success notice
    Engine-->>User: Capture complete

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–30 minutes

• Areas requiring attention:
  • Logic in captureAction.ts getCaptureAction() to ensure "activeFileTop" is returned only in the correct conditions
  • Backward compatibility handling in CaptureChoice.Load() method to ensure existing saved choices default activeFileWritePosition properly
  • UI state reset logic in captureChoiceBuilder.ts when switching between write-position options
  • Template runner condition in captureChoiceFormatter.ts to confirm "activeFileTop" triggering is correct

Poem

🐰 A leap to the top, no more middle ground,
Where captures now dance at the file's crown!
Top of the page, crisp and clean,
The finest feature ever seen—
Hop-hop-hooray! ✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding a write-to-top-of-file option for capture to active file feature, directly addressing the PR's primary objective.
Linked Issues check	✅ Passed	The PR fully implements the feature request from #248 by adding a switch/option to insert captures at the top of the file instead of at cursor position, meeting the stated objective.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the write-to-top-of-file feature; no out-of-scope modifications detected across engine, types, formatters, and UI components.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/add-write-to-top-of-file-switch

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d63f8c9 and 762f757.

📒 Files selected for processing (7)

• src/engine/CaptureChoiceEngine.ts (3 hunks)
• src/engine/captureAction.test.ts (2 hunks)
• src/engine/captureAction.ts (2 hunks)
• src/formatters/captureChoiceFormatter.ts (1 hunks)
• src/gui/ChoiceBuilder/captureChoiceBuilder.ts (4 hunks)
• src/types/choices/CaptureChoice.ts (3 hunks)
• src/types/choices/ICaptureChoice.ts (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (2)

src/engine/CaptureChoiceEngine.ts (1)

src/engine/captureAction.ts (1)

• getCaptureAction (9-31)

src/engine/captureAction.test.ts (1)

src/engine/captureAction.ts (1)

• getCaptureAction (9-31)

🔇 Additional comments (14)

src/types/choices/ICaptureChoice.ts (1)

8-8: LGTM! Well-designed property addition.

The optional activeFileWritePosition property with a clear union type ("cursor" | "top") provides good type safety and maintains backward compatibility.

src/formatters/captureChoiceFormatter.ts (1)

68-72: LGTM! Consistent templating logic.

The extended condition correctly ensures templater runs when activeFileWritePosition === "top", maintaining consistency with the prepend and insertAfter flows where templating happens before content insertion.

src/engine/captureAction.test.ts (2)

13-13: LGTM! Proper test setup.

The test helper correctly defaults activeFileWritePosition to "cursor", matching the production default for backward compatibility.

---

83-107: LGTM! Comprehensive test coverage.

The three new tests thoroughly cover the activeFileTop action:

• Verifies correct action when activeFileWritePosition === "top"
• Confirms currentLine action for default "cursor" position
• Tests prioritization logic

src/engine/captureAction.ts (2)

3-3: LGTM! Clean type extension.

The new "activeFileTop" action type follows the existing pattern and is well-integrated into the union type.

---

14-20: LGTM! Correct conditional logic.

The new conditional properly checks for activeFileWritePosition === "top" within the appropriate context (active file capture without prepend or insertAfter), and correctly falls through to "currentLine" for the default "cursor" position.

src/types/choices/CaptureChoice.ts (3)

10-10: LGTM! Proper property declaration.

The non-optional property declaration is appropriate here since the class always initializes it with a default value, unlike the interface which keeps it optional for backward compatibility.

---

45-45: LGTM! Sensible default.

The constructor correctly initializes activeFileWritePosition to "cursor", maintaining the existing default behavior.

---

76-81: LGTM! Excellent backward compatibility handling.

The Load method explicitly defaults falsy activeFileWritePosition values to "cursor", ensuring old configurations without this property continue to work with the expected default behavior.

src/engine/CaptureChoiceEngine.ts (2)

76-76: LGTM! Consistent success messaging.

The success message correctly treats "activeFileTop" the same as "prepend" since both insert content at the top of the file.

---

131-138: LGTM! Clear refactoring with correct logic.

The introduction of isEditorInsertionAction improves readability. The logic correctly excludes "activeFileTop" from editor insertion actions, ensuring it follows the vault.modify path (like "prepend") rather than direct editor insertion.

src/gui/ChoiceBuilder/captureChoiceBuilder.ts (3)

294-296: LGTM! Proper initialization.

The explicit initialization of activeFileWritePosition to "cursor" when undefined ensures backward compatibility for existing configurations.

---

306-322: LGTM! Well-structured position logic.

The current position computation correctly handles the new "activeTop" case within the priority order, and the UI appropriately shows the "Top of file (after frontmatter)" option only for active files.

---

330-358: LGTM! Correct state management.

The onChange handler properly:

• Resets activeFileWritePosition to "cursor" for all selections (line 345)
• Sets it to "top" only when "activeTop" is explicitly selected (line 354)
• Maintains the correct state for all other write position options

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🎉 This PR is included in version 2.8.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🚀 Release has been published: v2.8.0