Imported from LittleHaku/quotecard.koplugin (AGENTS.md). Install upstream with npx skills add LittleHaku/quotecard.koplugin. Copyright stays with the author.

Quote card contributor guide

Project scope

This repository is a standalone KOReader plugin. Its MVP has one entry point: the Quote card item in the reader's text-selection dialog. The item displays the current selection, book title, and author in a full-screen e-ink card.

Keep the MVP deliberately narrow. Do not add random highlights, exporting, sharing, screenshots, cover art, persistence, or settings unless the user explicitly expands the scope.

Compatibility invariants

• Keep _meta.lua and main.lua at the repository root. The repository and installed directory must remain named quotecard.koplugin so KOReader and KOReader App Store can detect it.
• Follow KOReader's built-in qrclipboard.koplugin pattern for addToHighlightDialog(): call highlightFromHoldPos() and require pos0, pos1, and non-empty selected_text.text before acting.
• Do not extend the selection to a sentence. Run selected_text.text through KOReader's util.cleanupSelectedText() before rendering it, then frame it with typographic quotation marks.
• Read metadata from ui.doc_props, preferring display_title, then title, and using authors when present.
• Preserve tap-anywhere dismissal, Back-key dismissal, full-screen repainting, bidirectional text support, left-aligned adaptive typography, optical vertical balance, and the scroll fallback for unusually long selections.
• Prefer KOReader's existing widgets and APIs over bundled dependencies.
• ZenUI replaces the highlight popup and filters unrecognized third-party actions unless Reader → Highlight/Lookup → Show other items is enabled. Keep Quote card on KOReader's public highlight-dialog API; do not impersonate one of ZenUI's built-in action identifiers to bypass that user preference.

Code layout

• main.lua: KOReader hook and quote-card UI.
• quote_data.lua: dependency-free selection and metadata rules.
• _meta.lua: plugin-manager metadata.
• tests/quote_data_test.lua: fast unit tests for the dependency-free rules.
• README.md: user installation and usage documentation.

Validation

Run the dependency-free tests with a Lua 5.1-compatible runtime or LuaJIT:

lua tests/quote_data_test.lua

Also parse-check every Lua file and, when working inside a KOReader checkout, run KOReader's luacheck/./kodev test workflow and exercise the plugin in the emulator with both a reflowable book and a PDF.

Before publishing, confirm that the Git worktree contains no generated files or temporary KOReader checkouts and that main tracks upstream/main.

Branching and publishing

• Use conventional task prefixes for branches: feat/, fix/, chore/, docs/, test/, or another matching prefix.
• Do not use an agent/ branch prefix.

Upstream references

• Plugin loading: https://koreader.rocks/doc/modules/pluginloader.html
• Unit tests: https://koreader.rocks/doc/topics/Unit_tests.md.html
• Selection hook reference: https://github.com/koreader/koreader/tree/master/plugins/qrclipboard.koplugin