@kurokeita/add-skill 1.20.0 → 2.0.0

package/dist/skills/koreader-plugin-development/references/events-and-widgets.md

@@ -0,0 +1,102 @@
+# Events and Widgets
+
+## Class hierarchy
+
+```
+EventListener           -- ui.widget.eventlistener (handleEvent)
+└── Widget              -- ui.widget.widget
+    └── WidgetContainer -- ui.widget.container.widgetcontainer
+        ├── FrameContainer, CenterContainer, BottomContainer, ...
+        ├── InputContainer  (gesture handling)
+        ├── ReaderUI / FileManager (top-level hosts)
+        └── any plugin extending WidgetContainer
+```
+
+All widgets inherit `handleEvent`. `WidgetContainer` overrides it to first propagate to children; if no child returns `true`, the container's own `on<EventName>` runs.
+
+## Sending an event
+
+```lua
+widget:handleEvent(Event:new("Timeout"))         -- direct, may be unsafe if widget destroys itself
+UIManager:sendEvent(Event:new("PageUpdate", 5))  -- from topmost widget down
+UIManager:broadcastEvent(Event:new("CloseDocument")) -- to every widget on the stack
+```
+
+`Event:new(name, arg1, arg2, ...)` packs args; the receiver implements `on<Name>(self, arg1, arg2, ...)`.
+
+## The event consumption contract
+
+```lua
+function MyPlugin:onPageUpdate(new_pageno)
+    if not self.enabled then return end   -- do not consume
+    self:doWork(new_pageno)
+    return true                            -- stop propagation
+end
+```
+
+- `return true` — consume; sibling widgets and the container's own handler are skipped.
+- `return nil`/`false` — let propagation continue.
+
+Consumption is the most common source of "my plugin runs but the reader stops responding to taps" bugs. Consume only events whose semantics you fully replace.
+
+## Common reader events
+
+| Event | When | Args |
+|-------|------|------|
+| `ReaderReady` | After document opens and modules initialized | `doc_settings` |
+| `CloseDocument` | Before tearing down ReaderUI | — |
+| `PosUpdate` | Reader rolling module signals scroll position change | `pos` |
+| `UpdatePos` | Typesetting changed; recompute layout | — |
+| `PageUpdate` | Page number changed | `new_pageno` |
+| `PageChangeAnimation` | Animated page turn | `forward` |
+| `BookMetadataChanged` | Metadata edited | `prop_updated` |
+| `Suspend` / `Resume` | Device sleep cycle | — |
+| `NetworkConnected` / `NetworkDisconnected` | Network state | — |
+
+## Common file-manager events
+
+| Event | When |
+|-------|------|
+| `PathChanged` | Directory navigated |
+| `BookmarkAdded` / `BookmarkRemoved` | Bookmark mutated |
+| `SetupShowReader` | About to launch Reader for a file |
+
+For exhaustive coverage, search KOReader source for `Event:new("` — every emit is grep-able.
+
+## UIManager lifecycle for widgets
+
+```lua
+UIManager:show(widget)        -- push onto _window_stack, schedule paint
+UIManager:setDirty(widget, "ui")  -- request redraw
+UIManager:close(widget)       -- pop, schedule repaint of stack below
+UIManager:scheduleIn(0.5, fn) -- run after 500ms
+UIManager:unschedule(fn)
+UIManager:nextTick(fn)        -- defer to next event loop tick
+```
+
+Always pair `show` with `close`. Widgets registered with `is_always_active = true` keep receiving events even when not at the top of the stack.
+
+## Useful built-in widgets
+
+| Widget | Purpose |
+|--------|---------|
+| `InfoMessage` | Modal info text with auto-close |
+| `ConfirmBox` | Yes/no prompt with callbacks |
+| `ButtonDialog` | Multi-button dialog from a 2D grid |
+| `InputDialog` | Text input with buttons |
+| `Notification` | Transient toast (no user dismissal) |
+| `Menu` | Scrollable list of items |
+| `KeyValuePage` | Two-column property display |
+| `TrapWidget` | Block input while a long task runs |
+
+All are under `ui.widget.*` and accept a table of properties to `:new{...}`.
+
+## Draw-page code path (for performance work)
+
+1. `ReaderView:recalculate` flags itself dirty.
+2. UIManager main loop calls `ReaderView:paintTo`.
+3. `ReaderView:paintTo` calls `document:drawPage`.
+4. `document:drawPage` checks the cache; if hit, returns the cached buffer.
+5. On miss, `document:renderPage` calls `_document:openPage`, `page:draw`, then caches the buffer.
+
+Hooking `ReaderView:paintTo` from a plugin can layer custom overlays per page; do it sparingly and never block.

package/dist/skills/koreader-plugin-development/references/patches.md

@@ -0,0 +1,118 @@
+# Patches (`koreader/patches/`)
+
+User patches are arbitrary Lua files in `koreader/patches/` that the `userpatch` module applies during startup. Use them when:
+
+- A plugin would be overkill for a one-line behavior change.
+- The change must run before plugins or before the UI builds.
+- Distributing a hotfix to users who can drop a single file into a directory.
+
+## Priority ordering
+
+`userpatch.applyPatches(priority)` is called multiple times during boot. Each call processes files whose name starts with the matching numeric prefix, sorted lexicographically.
+
+| Filename prefix | Phase | Run point | Typical use |
+|-----------------|-------|-----------|-------------|
+| `1-` | early-once | Very early, before most modules load | Set globals, env vars, monkey-patch core utilities |
+| `2-` | early | After core modules load, before UI | Override module methods that the UI then uses |
+| `3-` | late | After UI is built | Replace running widgets, mutate menus |
+
+A patch named `2-fix-readerfooter.lua` runs in the early phase; `3-add-menu.lua` runs late.
+
+## Patch skeleton
+
+```lua
+-- 2-stay-on-cover.lua
+-- Targets KOReader v2025.05+; remove if behavior is fixed upstream.
+
+local ReaderRolling = require("apps.reader.modules.readerrolling")
+local original_onReadSettings = ReaderRolling.onReadSettings
+
+function ReaderRolling:onReadSettings(config)
+    local res = original_onReadSettings(self, config)
+    if config:nilOrTrue("stay_on_cover") then
+        self:gotoPos(0)
+    end
+    return res
+end
+```
+
+Always:
+
+1. Capture the original function before replacement.
+2. Call the original from inside your override unless the goal is total replacement.
+3. Pass `self` and all args through unchanged.
+
+## Patch idioms
+
+### Add a method
+
+```lua
+local M = require("apps.reader.modules.readerbookmark")
+function M:exportAll()
+    -- ...
+end
+```
+
+### Wrap an existing method
+
+```lua
+local M = require("ui.widget.infomessage")
+local orig = M.init
+function M:init()
+    orig(self)
+    self.text = "[patched] " .. (self.text or "")
+end
+```
+
+### Replace a method
+
+```lua
+local M = require("apps.reader.modules.readerfooter")
+function M:onTapFooter() return false end
+```
+
+### Add a menu entry from a patch
+
+A patch can mutate the menu builder used by the UI — the safer option is to attach to an existing module's `addToMainMenu`:
+
+```lua
+local M = require("apps.reader.modules.readermenu")
+local orig = M.setUpdateItemTable
+function M:setUpdateItemTable()
+    orig(self)
+    self.menu_items.tools.sub_item_table[#self.menu_items.tools.sub_item_table + 1] = {
+        text = "Patched entry",
+        callback = function() end,
+    }
+end
+```
+
+For complex menu work, prefer a plugin.
+
+## Version guarding
+
+KOReader internals shift between releases. A patch that worked on v2025.04 may crash on v2025.07.
+
+```lua
+local Version = require("version")
+local current = Version:getCurrentRevision()
+if current < "v2025.05" then return end  -- skip if older
+```
+
+Always include a target-version comment header so users (and you, six months later) can audit at a glance.
+
+## Removal
+
+To disable a patch, delete it or rename it so the prefix no longer matches a known phase (e.g. `_off-2-foo.lua`). Patches do not auto-clean their effects on next boot — KOReader simply does not reapply them.
+
+Patches that allocate scheduled tasks or register listeners must clean up on `CloseDocument` / `Exit` if the user might disable them mid-session. Easier path: design patches to be idempotent and applied only at startup.
+
+## Failure mode
+
+A patch that errors during application aborts only that patch; remaining patches and the rest of boot continue. The traceback lands in `crash.log` with the patch filename. Always test with debug logging on (`./kodev run --debug`) before shipping.
+
+## When NOT to use a patch
+
+- Adding substantial new UI → write a plugin.
+- Anything users should be able to toggle → write a plugin.
+- Patching something that has an official extension hook → use the hook (events, dispatcher, `addToMainMenu`).

package/dist/skills/koreader-plugin-development/references/plugin-anatomy.md

@@ -0,0 +1,97 @@
+# Plugin Anatomy
+
+## Directory layout
+
+A plugin is a directory whose name matches `.+%.koplugin`. KOReader scans `DEFAULT_PLUGIN_PATH` (the bundled `plugins/` directory) plus any path listed in the `extra_plugin_paths` setting. The user setting `plugins_disabled` is a table of plugin names to skip.
+
+```
+MyPlugin.koplugin/
+├── _meta.lua        # plugin metadata (required for menu integration)
+├── main.lua         # returns the plugin class
+├── README.md        # optional, surfaced in the plugin manager UI
+├── i18n/            # optional Crowdin-style translations
+└── *.lua            # additional sub-modules
+```
+
+## `_meta.lua`
+
+Returns a plain table that pluginloader reads before instantiating `main.lua`. Minimum fields:
+
+```lua
+return {
+    name = "myplugin",            -- internal id, must match WidgetContainer name
+    fullname = _("My Plugin"),    -- shown in plugin manager
+    description = _([[One-paragraph description.]]),
+}
+```
+
+Optional fields recognized by the loader: `version`, `author`. The translation function `_` comes from `gettext` and is available in `_meta.lua` evaluation scope.
+
+## `main.lua` skeleton
+
+```lua
+local WidgetContainer = require("ui.widget.container.widgetcontainer")
+local InfoMessage = require("ui.widget.infomessage")
+local UIManager = require("ui.uimanager")
+local _ = require("gettext")
+
+local MyPlugin = WidgetContainer:extend{
+    name = "myplugin",
+    is_doc_only = false,   -- true: only load inside ReaderUI
+}
+
+function MyPlugin:init()
+    self.ui.menu:registerToMainMenu(self)
+end
+
+function MyPlugin:addToMainMenu(menu_items)
+    menu_items.myplugin = {
+        text = _("My plugin"),
+        sorting_hint = "tools",
+        callback = function()
+            UIManager:show(InfoMessage:new{ text = _("Hello from MyPlugin") })
+        end,
+    }
+end
+
+return MyPlugin
+```
+
+Key conventions:
+
+- `name` must be unique and match the directory stem.
+- `is_doc_only = true` restricts the plugin to ReaderUI; omit for both hosts.
+- `init` runs after the host UI built `self.ui`. Treat it as the plugin's constructor — register menus, dispatcher actions, and event listeners here.
+- Returning the class (not an instance) lets pluginloader instantiate per host.
+
+## Lifecycle and host wiring
+
+`pluginloader` instantiates plugins for the active UI host (`FileManager` or `ReaderUI`). Each instance is appended as a child of that host's `WidgetContainer`, so it receives every event the host receives via standard propagation.
+
+To register hooks beyond the menu:
+
+- Dispatcher actions (gestures, profiles): `Dispatcher:registerAction("my_action", { category = "none", event = "MyAction", title = _("My action"), general = true })` then handle `onMyAction`.
+- Background work: extend `ui.plugin.background_task_plugin`.
+- Toggle behavior: extend `ui.plugin.switch_plugin`.
+
+## Event handlers in plugins
+
+Implement `onFoo(self, ...)` to handle event `Foo`. The host UI broadcasts events down the tree; plugins receive them after host modules. Returning `true` stops propagation. Avoid swallowing events the reader needs (`PageUpdate`, `PosUpdate`) unless that is the goal.
+
+## Persistence
+
+- App-wide settings: `local LuaSettings = require("luasettings"); local s = LuaSettings:open(DataStorage:getSettingsDir() .. "/myplugin.lua")`.
+- Per-document state: `self.ui.doc_settings:saveSetting("myplugin_state", value)`. Saved with the document's metadata.
+- Always handle the case where the file does not yet exist; LuaSettings degrades to an empty table.
+
+## Internationalization
+
+Wrap user-visible strings: `local _ = require("gettext"); _("Save")`. For plurals, `gettext.ngettext("%1 page", "%1 pages", n)`. Translations live under KOReader's main `l10n/` tree; for in-tree plugins, use the project's translation pipeline. For out-of-tree plugins, you may ship strings English-only or vendor your own gettext catalog.
+
+## Loading errors
+
+Errors during plugin load disable the plugin silently for the user but log to `crash.log`. Defensive techniques:
+
+- Wrap optional dependencies (e.g. plugins that integrate with another plugin) in `pcall(require, "...")`.
+- Keep `_meta.lua` side-effect free — it loads in a plain `dofile` context.
+- Avoid top-level `require` of modules that only exist in newer KOReader versions; gate with `pcall` and fall back gracefully.