develop-kkmod-modules

# Develop KKMod Modules Build optional static web applications for KKTerm's isolated Custom Module runtime. Treat the installed KKTerm host implementation as authoritative. ## Mandatory preflight gate Before creating, editing, generating, installing, or packaging module files: 1. Inspect the proposed app and identify whether it needs a server, remote APIs, workers, frames, popups, persistent browser storage, clipboard/device APIs, arbitrary filesystem access, or Node.js at runtime. 2. Present this warning, adapted with concrete findings: > KKMod host API v2 runs local static browser assets in an isolated native WebView. It provides no HTTP/Node.js runtime, service/Shared Workers, remote frames, arbitrary shell/terminal/database access, media/device/sensor APIs, product-data brokers, or direct Tauri commands. Durable JSON, raw blobs, browser-native persistence, external links, clipboard, user-mediated file/directory tokens, bounded outbound requests, secret references, Status Bar host UI, and system path actions each require an explicit structured permission. A dedicated Worker may load only a packaged same-package script and has no host bridge. The Module must signal readiness within 15 seconds. 3. Classify the request as **compatible**, **compatible with adaptation**, or **incompatible with v2**. Name every required adaptation and requested permission. 4. Ask: **“Proceed with KKMod host API v2 under these constraints?”** 5. Stop before file mutations until the user explicitly confirms. Read-only inspection is allowed. If incompatible, propose a static/offline design or a host-platform change; do not silently remove core behavior. Present this gate once per development task. A user's explicit acceptance of these exact constraints in the current request counts as confirmation, but still report the compatibility classification before editing. ## Load the contract Read both references completely before implementation: - [Package contract](references/package-contract.md) — archive structure, strict manifest and catalog schemas, path/type/size rules, and licensing. - [Runtime API](references/runtime-api.md) — supported host features, bridge signatures, events, CSP, unavailable browser APIs, and adaptation patterns. When working inside a KKTerm checkout, also read `docs/CUSTOM_MODULE_PACKAGING.md` and the constants, manifest structs, validators, initialization script, bridge, and protocol response in `src-tauri/src/custom_modules.rs`. If they differ from this skill, follow the checkout and update this skill if requested. When changing the KKTerm host itself, keep every Tauri command that constructs a Custom Module `WebviewWindow` asynchronous. On Windows, WebView2 window construction from a synchronous command can deadlock Tauri's IPC dispatcher, leaving `window.KKTerm.ready()` and unrelated invokes pending. On macOS, dispatch AppKit window ordering through Tauri's main-thread runner; calling `NSWindow.orderFront` from the asynchronous startup worker can terminate KKTerm when a Custom Module starts or is restored at launch. ## Workflow 1. **Define the outcome.** Record the package id, publisher, semantic version, license, contribution ids/titles/icons, offline behavior, durable-data needs, external links, and source/build toolchain. Design the packaged application as an edge-to-edge child-panel surface with its own visible title, navigation, and application chrome; KKTerm deliberately supplies no per-Module header. For KKTerm-curated publication, every rail-visible contribution needs distinct, attributable SVG artwork suitable for a monochrome Activity Rail mask. 2. **Audit feasibility.** Inventory every runtime URL, dependency, worker/service worker, iframe, inline script, navigation route, browser persistence call, device API, secret, font, asset, and license. Resolve each against the runtime reference. Inspect the production bundles as well as application source: a library's `worker: true`, `workerBlobURL`, worker pool, or feature probe can create a Blob/data Worker indirectly. A constructor that returns before the CSP error event can leave a document loader or processing promise pending forever. 3. **Choose the starting point.** For a new module, copy `assets/starter-kkmod/`. For an existing app, preserve its source project but emit a self-contained production build into `dist/`. 4. **Adapt for isolation.** Use relative local asset URLs, external script files, declared `static`/`spa` routing, packaged same-package dedicated Workers/frames, and the narrow `window.KKTerm` bridge. Workers communicate through `postMessage` and cannot call the bridge. For dependencies that generate Blob/data Workers, choose a supported direct or main-thread mode, or extract the worker into a packaged script and pass its same-package URL. Do not loosen the host CSP to accommodate a dependency. Replace runtime CDNs and direct cross-origin fetches with packaged assets or `network.fetch`. Standard local Blob/data/same-package `<a download>` helpers may remain because the host mediates them through `files.save`; remote download URLs may not. Do not expose secrets through module storage. Validate the final packaged HTML, not only source templates: every local HTML asset reference must resolve inside the package's `dist/` directory. Reject root-absolute references such as `/assets/app.js` and traversal such as `../../assets/app.js` from `dist/*.html`; use `./assets/app.js` (or the correct relative path for nested pages). 5. **Declare least privilege.** Use the structured permission object. Request only the store, browser persistence, clipboard, external link, file/directory filters, exact network origins/methods, secret references, host UI, and token-bound host integration the Module actually uses. Inventory browser file inputs/drops plus every import and export extension, not only explicit `KKTerm.files` calls. Product-data proposal permissions are not part of v2. 6. **Integrate lifecycle.** Read initial context/capabilities; subscribe to `contextChanged`, `visibilityChanged`, `focusChanged`, `suspending`, and `closing`; apply theme/locale changes; handle typed bridge errors; and call `window.KKTerm.ready()` only after the usable UI has initialized. Finish within 15 seconds. KKTerm's UI locale is authoritative: await a fresh `window.KKTerm.getContext()` before initializing Module i18n because the injected `window.KKTerm.context` may be a startup snapshot during same-WebView navigation. Select the exact bundled host locale first, then an intentional compatible base-locale mapping, and fall back to English only when no translation exists. Preserve distinctions such as `zh-TW` versus `zh-CN`; never map Taiwan Chinese to a Mainland Chinese translation. Apply later `contextChanged` locale updates live, and remove or disable any Module-owned language preference or picker that could drift from KKTerm. 7. **Audit licenses.** Include the package's license and all required third-party notices. Recheck bundled dependencies, fonts, icons, examples, and media for the exact release version. Record the source and license of curated Activity Rail artwork. 8. **Validate and package.** Run: ```powershell python <skill-dir>\scripts\kkmod_tool.py check <module-root> python <skill-dir>\scripts\kkmod_tool.py pack <module-root> <name>.kkmod python <skill-dir>\scripts\kkmod_tool.py check <name>.kkmod ``` 9. **Verify behavior.** Test in the real Tauri desktop runtime: startup/readiness, keyboard and focus, resizing, theme/locale updates, overlay visibility, restart persistence, permissions, clipboard copy/paste when granted, native and drag/drop file input, every distinct local export/download helper, save cancellation, offline startup, disable/uninstall, and URL/RDP overlap. Exercise every distinct generated HTML entry (or crawl them automatically) so broken asset paths cannot hide on secondary tool pages. For every worker-backed viewer or processor, load a representative input under the host CSP, check the browser console for worker violations, and assert that the operation completes or shows an actionable error instead of retaining a spinner or pending promise. Verify at least one supported non-English KKTerm locale and one unsupported locale that must fall back to English. For Windows portable builds, verify install, restart, folder move, and update retention with SQLite metadata in `data/kkterm.sqlite3` and every package/document/WebView/catalog/download/staging artifact below `data/custom-modules/`. Browser/Vite preview is insufficient for native integration. If host code changed, also verify that starting a Module does not stall unrelated main-window Tauri invokes. 10. **Prepare publication only when requested.** Ensure every rail-visible curated contribution declares an inert packaged SVG icon no larger than 64 KiB; KKTerm renders it as a monochrome `currentColor` mask. Generate catalog metadata from the final immutable archive, sign its lowercase SHA-256 text outside the repository, and keep the private key out of source and package files. ## Completion report Report: - compatibility classification and adaptations made; - package id/version, contributions, permissions, and license/notices; - `.kkmod` path, byte size, SHA-256, expanded size, and file count; - validation and real-runtime checks performed; - any remaining release-QA or catalog-signing work. Never claim catalog readiness without a dependency/license audit, immutable HTTPS artifact, matching metadata, and valid Ed25519 signature.