diff --git a/backlog/tasks/task-112 - Fix-docs-demo-video-thumbnail-cache-staleness.md b/backlog/tasks/task-112 - Fix-docs-demo-video-thumbnail-cache-staleness.md new file mode 100644 index 0000000..f636dfc --- /dev/null +++ b/backlog/tasks/task-112 - Fix-docs-demo-video-thumbnail-cache-staleness.md @@ -0,0 +1,50 @@ +--- +id: TASK-112 +title: Fix docs demo video thumbnail cache staleness +status: Done +assignee: + - codex +created_date: '2026-02-23 03:41' +updated_date: '2026-02-23 03:43' +labels: + - bug + - docs + - media +dependencies: [] +priority: medium +ordinal: 112000 +--- + +## Description + + +Docs home page demo continues to show an old thumbnail after replacing the demo video file in place. The page currently reuses static media URLs (`/assets/minecard.webm`, `/assets/minecard.mp4`, `/assets/demo-poster.jpg`), so browser/CDN cache can keep stale poster/video preview data. + + +## Action Steps + + +1. Add a failing regression check that asserts cache-busted URL usage for docs home demo media references. +2. Update docs home demo media URLs to include a shared asset version token for poster/source/fallback paths. +3. Run the regression check and docs build validation. +4. Record fix notes and move task status to Done. + + +## Acceptance Criteria + +- [x] #1 Docs home video references include a deterministic cache-busting token so direct asset replacement does not serve stale preview data. +- [x] #2 Poster/source/fallback links in the demo block use the same token to avoid mixed old/new media. +- [x] #3 Validation commands for the new regression check and docs build pass. + + +## Implementation Notes + + +- Generated a fresh thumbnail from `docs/public/assets/minecard.webm` into `docs/public/assets/minecard-poster.jpg`. +- Updated `docs/index.md` demo block to use a shared `demoAssetVersion` token across poster, webm/mp4 sources, and gif fallback links. +- Follow-up: regenerated `minecard-poster.jpg` at exact `00:00:12` from the webm and bumped token to `demoAssetVersion = '20260223-2'`. +- Added regression check `docs/index.assets.test.ts` to ensure demo media references keep shared cache-busting URL patterns. +- Validation: + - `bun test docs/index.assets.test.ts` + - `bun run docs:build` + diff --git a/backlog/tasks/task-113 - Refresh-architecture-doc-content-to-match-current-codebase.md b/backlog/tasks/task-113 - Refresh-architecture-doc-content-to-match-current-codebase.md new file mode 100644 index 0000000..5b40fc2 --- /dev/null +++ b/backlog/tasks/task-113 - Refresh-architecture-doc-content-to-match-current-codebase.md @@ -0,0 +1,33 @@ +--- +id: TASK-113 +title: Refresh architecture doc content to match current codebase +status: Done +assignee: + - codex-architecture-doc-refresh +created_date: '2026-02-22 19:39' +updated_date: '2026-02-22 19:44' +labels: + - docs + - architecture +dependencies: [] +priority: low +--- + +## Description + + +User requested a thorough review of the current codebase and `docs/architecture.md`, then updating document content to reflect current implementation details. Mermaid/flow diagrams are explicitly out of scope for this pass. + + +## Acceptance Criteria + +- [x] #1 Architecture content sections align with current source tree/module ownership. +- [x] #2 Service/composer/runtime descriptions are updated for current behavior and module names. +- [x] #3 Mermaid/flow chart sections remain unchanged in this pass. + + +## Notes + +- Reviewed current module ownership across `src/main.ts`, `src/main/runtime/*`, `src/core/services/*`, `src/config/*`, `src/renderer/*`, `launcher/*`, and `plugin/subminer.lua`. +- Updated `docs/architecture.md` content sections only; Mermaid blocks intentionally left untouched. +- Verification: `bun run docs:build` passed. diff --git a/backlog/tasks/task-114 - Refresh-development-doc-content-to-match-current-codebase.md b/backlog/tasks/task-114 - Refresh-development-doc-content-to-match-current-codebase.md new file mode 100644 index 0000000..17bb73e --- /dev/null +++ b/backlog/tasks/task-114 - Refresh-development-doc-content-to-match-current-codebase.md @@ -0,0 +1,35 @@ +--- +id: TASK-114 +title: Refresh development doc content to match current codebase +status: Done +assignee: + - codex-development-docs-review +created_date: '2026-02-23 03:46' +updated_date: '2026-02-23 03:49' +labels: + - docs + - developer-experience +dependencies: [] +priority: medium +--- + +## Description + + +User requested a thorough review of the current codebase and `docs/development.md`, then updates so the page reflects current scripts, architecture, and contributor workflow. + + +## Acceptance Criteria + +- [x] #1 `docs/development.md` commands/tooling sections match current `package.json`, `Makefile`, and active CI lanes. +- [x] #2 Runtime/composition guidance reflects current module ownership and does not reference removed guardrail steps. +- [x] #3 Updated doc builds cleanly via `bun run docs:build`. + + +## Notes + +- Reviewed `docs/development.md` against current `package.json` scripts, `Makefile` targets, launcher/runtime env overrides, and `.github/workflows/ci.yml` gate order. +- Updated setup instructions to use Bun for `vendor/texthooker-ui` and include submodule initialization. +- Added CI-equivalent local test/build/docs command sequence and clarified that subtitle dist tests are currently placeholders. +- Expanded environment-variable coverage (`SUBMINER_ROFI_THEME`, Jimaku/Jellyfin overrides, `SUBMINER_LOG_LEVEL`, `SUBMINER_MPV_LOG`, macOS helper skip flag). +- Verification: `bun run docs:build` passed. diff --git a/docs/architecture.md b/docs/architecture.md index 52fc6db..89095b8 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,6 +1,12 @@ # Architecture -SubMiner uses a service-oriented Electron architecture with a composition-oriented main process and a modular renderer process. +SubMiner is split into three cooperating runtimes: + +- Electron desktop app (`src/`) for overlay/UI/runtime orchestration. +- Launcher CLI (`launcher/`) for mpv/app command workflows. +- mpv Lua plugin (`plugin/subminer.lua`) for player-side controls and IPC handoff. + +Within the desktop app, `src/main.ts` is a composition root that wires small runtime/domain modules plus core services. ## Goals @@ -15,31 +21,52 @@ SubMiner uses a service-oriented Electron architecture with a composition-orient ## Project Structure ```text +launcher/ # Standalone CLI launcher wrapper and mpv helpers + commands/ # Command modules (doctor/config/mpv/jellyfin/playback/app passthrough) + config/ # Launcher config parsers + CLI parser builder + main.ts # Launcher entrypoint and command dispatch +plugin/ + subminer.lua # mpv plugin (auto-start, IPC, AniSkip + hover controls) src/ + main-entry.ts # Background-mode bootstrap wrapper before loading main.js main.ts # Entry point — delegates to runtime composers/domain modules preload.ts # Electron preload bridge types.ts # Shared type definitions - main/ # Composition root modules (extracted from main.ts) - app-lifecycle.ts # Electron lifecycle event registration - cli-runtime.ts # CLI command handling and dispatch - dependencies.ts # Shared dependency builders for IPC/runtime - ipc-mpv-command.ts # MPV command composition helpers - ipc-runtime.ts # IPC channel registration and handlers - overlay-runtime.ts # Overlay window/modal selection and state + main/ # Main-process composition/runtime adapters + app-lifecycle.ts # App lifecycle + app-ready runtime runner factories + cli-runtime.ts # CLI command runtime service adapters + config-validation.ts # Startup/hot-reload config error formatting and fail-fast helpers + dependencies.ts # Shared dependency builders for IPC/runtime services + ipc-runtime.ts # IPC runtime registration wrappers + overlay-runtime.ts # Overlay modal routing + active-window selection overlay-shortcuts-runtime.ts # Overlay keyboard shortcut handling - startup.ts # Startup bootstrap flow (argv/env processing) - startup-lifecycle.ts # App-ready initialization sequence - state.ts # Application runtime state container - subsync-runtime.ts # Subsync command orchestration + overlay-visibility-runtime.ts # Overlay visibility + tracker-driven bounds service + frequency-dictionary-runtime.ts # Frequency dictionary runtime adapter + jlpt-runtime.ts # JLPT dictionary runtime adapter + media-runtime.ts # Media path/title/subtitle-position runtime service + startup.ts # Startup bootstrap dependency builder + startup-lifecycle.ts # Lifecycle runtime runner adapter + state.ts # Application runtime state container + reducer transitions + subsync-runtime.ts # Subsync command runtime adapter runtime/ - composers/ # Composition assembly clusters consumed by main.ts - domains/ # Domain barrel exports for runtime services + composers/ # High-level composition clusters used by main.ts + domains/ # Domain barrel exports (startup/overlay/mpv/jellyfin/...) + registry.ts # Domain registry consumed by main.ts core/ - services/ # ~60 focused service modules (see below) + services/ # Focused runtime services (Electron adapters + pure logic) + anilist/ # AniList token store/update queue/update helpers + immersion-tracker/ # Immersion persistence/session/metadata modules + tokenizer/ # Tokenizer stage modules (selection/enrichment/annotation) utils/ # Pure helpers and coercion/config utilities cli/ # CLI parsing and help output - config/ # Config schema, defaults, validation, template generation + config/ # Config defaults/definitions, loading, parse, resolution pipeline + definitions/ # Domain-specific defaults + option registries + resolve/ # Domain-specific config resolution pipeline stages + shared/ipc/ # Cross-process IPC channel constants + payload validators renderer/ # Overlay renderer (modularized UI/runtime) + handlers/ # Keyboard/mouse interaction modules + modals/ # Jimaku/Kiku/subsync/runtime-options/session-help modals + positioning/ # Invisible-layer layout + offset controllers window-trackers/ # Backend-specific tracker implementations (Hyprland, Sway, X11, macOS) jimaku/ # Jimaku API integration helpers subsync/ # Subtitle sync (alass/ffsubsync) helpers @@ -51,27 +78,32 @@ src/ ### Service Layer (`src/core/services/`) -- **Startup** — `startup-service`, `app-lifecycle-service`, `app-ready-service` -- **Overlay** — `overlay-manager-service`, `overlay-window-service`, `overlay-visibility-service`, `overlay-bridge-service`, `overlay-runtime-init-service`, `overlay-content-measurement-service` -- **Shortcuts** — `shortcut-service`, `overlay-shortcut-service`, `overlay-shortcut-handler`, `shortcut-fallback-service`, `numeric-shortcut-service`, `numeric-shortcut-session-service` -- **MPV** — `mpv-service`, `mpv-control-service`, `mpv-render-metrics-service`, `mpv-transport`, `mpv-protocol`, `mpv-state`, `mpv-properties` -- **IPC** — `ipc-service`, `ipc-command-service`, `runtime-options-ipc-service` -- **Mining** — `mining-service`, `field-grouping-service`, `field-grouping-overlay-service`, `anki-jimaku-service`, `anki-jimaku-ipc-service` -- **Subtitles** — `subtitle-ws-service`, `subtitle-position-service`, `secondary-subtitle-service`, `tokenizer-service` -- **Integrations** — `jimaku-service`, `subsync-service`, `subsync-runner-service`, `texthooker-service`, `yomitan-extension-loader-service`, `yomitan-settings-service` -- **Config** — `runtime-config-service`, `cli-command-service` +- **Overlay/window runtime:** `overlay-manager.ts`, `overlay-window.ts`, `overlay-window-geometry.ts`, `overlay-visibility.ts`, `overlay-bridge.ts`, `overlay-runtime-init.ts`, `overlay-content-measurement.ts`, `overlay-drop.ts` +- **Shortcuts/input:** `shortcut.ts`, `overlay-shortcut.ts`, `overlay-shortcut-handler.ts`, `shortcut-fallback.ts`, `numeric-shortcut.ts` +- **MPV runtime:** `mpv.ts`, `mpv-transport.ts`, `mpv-protocol.ts`, `mpv-properties.ts`, `mpv-render-metrics.ts` +- **Mining + Anki/Jimaku runtime:** `mining.ts`, `field-grouping.ts`, `field-grouping-overlay.ts`, `anki-jimaku.ts`, `anki-jimaku-ipc.ts` +- **Subtitle/token pipeline:** `subtitle-processing-controller.ts`, `subtitle-position.ts`, `subtitle-ws.ts`, `tokenizer.ts` + `tokenizer/*` stage modules +- **Integrations:** `jimaku.ts`, `subsync.ts`, `subsync-runner.ts`, `texthooker.ts`, `jellyfin.ts`, `jellyfin-remote.ts`, `discord-presence.ts`, `yomitan-extension-loader.ts`, `yomitan-settings.ts` +- **Config/runtime controls:** `config-hot-reload.ts`, `runtime-options-ipc.ts`, `cli-command.ts`, `startup.ts` +- **Domain submodules:** `anilist/*` (token/update queue/updater), `immersion-tracker/*` (storage/session/metadata/query/reducer) ### Renderer Layer (`src/renderer/`) -The overlay renderer is split by concern so `renderer.ts` stays focused on bootstrapping, IPC wiring, and module composition. +The renderer keeps `renderer.ts` focused on orchestration. UI behavior is delegated to per-concern modules. ```text src/renderer/ renderer.ts # Entrypoint/orchestration only context.ts # Shared runtime context contract state.ts # Centralized renderer mutable state + error-recovery.ts # Global renderer error boundary + recovery actions + overlay-content-measurement.ts # Reports rendered bounds to main process subtitle-render.ts # Primary/secondary subtitle rendering + style application - positioning.ts # Visible/invisible positioning + mpv metrics layout + positioning.ts # Facade export for positioning controller + positioning/ + controller.ts # Position controller orchestration + invisible-layout*.ts # Invisible layer layout computations + position-state.ts # Position state helpers handlers/ keyboard.ts # Keybindings, chord handling, modal key routing mouse.ts # Hover/drag behavior, selection + observer wiring @@ -79,12 +111,18 @@ src/renderer/ jimaku.ts # Jimaku modal flow kiku.ts # Kiku field-grouping modal flow runtime-options.ts # Runtime options modal flow + session-help.ts # Keyboard shortcuts/help modal flow subsync.ts # Manual subsync modal flow utils/ dom.ts # Required DOM lookups + typed handles platform.ts # Layer/platform capability detection ``` +### Launcher + Plugin Runtimes + +- `launcher/main.ts` dispatches commands through `launcher/commands/*` and shared config readers in `launcher/config/*`. It handles mpv startup, app passthrough, Jellyfin helper commands, and playback handoff. +- `plugin/subminer.lua` runs inside mpv and handles IPC startup checks, overlay toggles, hover-token messages, and AniSkip intro-skip UX. + ## Flow Diagram The main process has three layers: `main.ts` delegates to composition modules that wire together domain services. The renderer runs in a separate Electron process, connected through `preload.ts`. @@ -179,6 +217,12 @@ Composer modules share contract conventions via `src/main/runtime/composers/cont This keeps side effects explicit and makes behavior easy to unit-test with fakes. +Additional conventions in the current code: + +- `main.ts` uses `createMainRuntimeRegistry()` (`src/main/runtime/registry.ts`) to access domain handlers (`startup`, `overlay`, `mpv`, `ipc`, `shortcuts`, `anilist`, `jellyfin`, `mining`) without importing every runtime module directly. +- Domain barrels in `src/main/runtime/domains/*` re-export runtime handlers + main-deps builders, while composers in `src/main/runtime/composers/*` assemble larger runtime clusters. +- Many runtime handlers accept `*MainDeps` objects generated by `createBuild*MainDepsHandler` builders to isolate side effects and keep units testable. + ### IPC Contract + Validation Boundary - Central channel constants live in `src/shared/ipc/contracts.ts` and are consumed by both main (`ipcMain`) and renderer preload (`ipcRenderer`) wiring. @@ -199,9 +243,10 @@ For domains migrated to reducer-style transitions (for example AniList token/que ## Program Lifecycle - **Startup:** `startup.ts` parses CLI args and detects the compositor backend. If `--generate-config` is passed, it writes the template and exits. Otherwise `app-lifecycle.ts` acquires the single-instance lock and registers Electron lifecycle hooks. -- **Initialization:** Once `app.whenReady()` fires, `startup-lifecycle.ts` runs a short critical path first (config reload, keybindings, mpv client, overlay setup, IPC bridge), then schedules non-critical warmups in the background (MeCab availability check, Yomitan extension load, dictionary prewarm, optional Jellyfin remote startup). -- **Runtime:** Event-driven. mpv property changes, IPC messages, CLI commands, and keyboard shortcuts all route through the composition layer to domain services, which update state and broadcast to the renderer. -- **Shutdown:** Electron's `will-quit` triggers service teardown — closes the mpv socket, unregisters shortcuts, stops WebSocket and texthooker servers, destroys the window tracker, and cleans up Anki state. +- **Initialization:** Once `app.whenReady()` fires, `composeAppReadyRuntime()` runs the critical path first (strict config reload, runtime options + keybindings, mpv client creation, overlay/IPC setup). Non-critical warmups are launched asynchronously (`mecab`, `yomitan-extension`, dictionary prewarm, optional Jellyfin remote session). +- **Runtime:** Event-driven. mpv events, IPC messages, CLI commands, overlay shortcuts, hot-reload notifications, and integration callbacks route through runtime handlers/composers, update `AppState`, and broadcast to overlay windows. +- **Overlay window model:** runtime manages three overlay windows: `visible`, `invisible`, and `secondary`. `splitOverlayGeometryForSecondaryBar()` reserves the top 20% for the secondary subtitle bar and routes the remaining area to the active primary overlay layer. +- **Shutdown:** `onWillQuitCleanup` tears down tray + watchers + integrations, stops subtitle/texthooker servers, flushes buffered MPV OSD log writes, closes token/session windows, and stops Jellyfin/Discord runtime services. ```mermaid flowchart TD @@ -252,15 +297,15 @@ flowchart TD - **Better testability:** most behavior can be tested without Electron windows/mpv. - **Better reviewability:** PRs can be scoped to one subsystem. - **Backward compatibility:** CLI flags and IPC channels can remain stable while internals evolve. -- **Extracted composition root:** `main.ts` delegates to focused modules under `src/main/` for startup, lifecycle, IPC, CLI, and domain runtime wiring. -- **Split MPV service layers:** MPV internals are separated into transport (`mpv-transport.ts`), protocol (`mpv-protocol.ts`), state (`mpv-state.ts`), and properties (`mpv-properties.ts`) for maintainability. +- **Runtime registry + domain barrels:** `src/main/runtime/registry.ts` and `src/main/runtime/domains/*` reduce direct fan-in inside `main.ts` while keeping domain ownership explicit. +- **Extracted composition root:** `main.ts` delegates to focused modules under `src/main/` and `src/main/runtime/composers/` for lifecycle, IPC, overlay, mpv, shortcut, and integration wiring. +- **Split MPV service layers:** MPV internals are separated into transport (`mpv-transport.ts`), protocol (`mpv-protocol.ts`), and properties/render metrics modules for maintainability. +- **Config by domain:** defaults, option registries, and resolution are split by domain under `src/config/definitions/*` and `src/config/resolve/*`, keeping config evolution localized. ## Extension Rules -- Add behavior to an existing service in `src/core/services/*` or create a focused composition module in `src/main/` / `src/main/runtime/composers/` — not as ad-hoc logic in `main.ts`. -- Keep service APIs explicit and narrowly scoped. -- Prefer additive changes that preserve existing CLI flags and IPC channel behavior. -- Add/update unit tests for each service extraction or behavior change. -- For cross-cutting changes, extract-first then refactor internals after parity is verified. -- When adding new IPC channels or CLI commands, register them in the appropriate `src/main/` module (`ipc-runtime.ts` for IPC, `cli-runtime.ts` for CLI). -- When adding/changing IPC channels, update `src/shared/ipc/contracts.ts`, validate payloads in `src/shared/ipc/validators.ts`, and add malformed-payload tests. +- Add behavior to an existing service in `src/core/services/*` or create a focused runtime module under `src/main/runtime/*`; avoid ad-hoc logic in `main.ts`. +- Add new cross-process channels in `src/shared/ipc/contracts.ts` first, validate payloads in `src/shared/ipc/validators.ts`, then wire handlers in IPC runtime modules. +- If change spans startup/overlay/mpv/integration wiring, prefer composing through `src/main/runtime/domains/*` + `src/main/runtime/composers/*` rather than direct wiring in `main.ts`. +- Keep service APIs explicit and narrowly scoped, and preserve existing CLI flag / IPC channel behavior unless the change is intentionally breaking. +- Add or update focused tests (including malformed-payload IPC tests) when runtime boundaries or contracts change. diff --git a/docs/development.md b/docs/development.md index ab937f9..3ae6b86 100644 --- a/docs/development.md +++ b/docs/development.md @@ -8,12 +8,15 @@ ## Setup ```bash -git clone https://github.com/ksyasuda/SubMiner.git +git clone --recurse-submodules https://github.com/ksyasuda/SubMiner.git cd SubMiner +# if you cloned without --recurse-submodules: +git submodule update --init --recursive + make deps # or manually: bun install -cd vendor/texthooker-ui && pnpm install --frozen-lockfile +(cd vendor/texthooker-ui && bun install --frozen-lockfile) ``` ## Building @@ -47,6 +50,7 @@ Verify the workflow: ```bash make build-launcher +dist/launcher/subminer --help >/dev/null bash scripts/verify-generated-launcher.sh ``` @@ -56,16 +60,29 @@ bash scripts/verify-generated-launcher.sh bun run dev # builds + launches with --start --dev electron . --start --dev --log-level debug # equivalent Electron launch with verbose logging electron . --background # tray/background mode, minimal default logging +make dev-start # build + launch via Makefile ``` ## Testing +CI-equivalent local gate: + +```bash +bun run tsc --noEmit +bun run test:fast +bun run test:launcher:smoke:src +bun run build +bun run test:smoke:dist +bun run docs:build +``` + +Common focused commands: + ```bash bun run test:config # Source-level config schema/validation tests bun run test:launcher # Launcher regression tests (config discovery + command routing) bun run test:launcher:smoke:src # Launcher e2e smoke: launcher -> mpv IPC -> overlay start/stop wiring bun run test:core # Source-level core regression tests (default lane) -bun run test:subtitle # Subtitle pipeline tests (build + run) bun run test:fast # Source-level config + core lane (no build prerequisite) ``` @@ -80,9 +97,10 @@ bun run build # compile dist artifacts bun run test:smoke:dist # explicit smoke scope for compiled runtime bun run test:config:dist # optional full dist config suite bun run test:core:dist # optional full dist core suite -bun run test:subtitle:dist # optional smoke lane for subtitle dist regressions ``` +`bun run test:subtitle` and `bun run test:subtitle:dist` are currently placeholders and do not run an active suite. + ## Config Generation ```bash @@ -111,6 +129,7 @@ Run `make help` for a full list of targets. Key ones: | Target | Description | | ---------------------- | ---------------------------------------------------------------- | | `make build` | Build platform package for detected OS | +| `make build-launcher` | Generate Bun launcher wrapper at `dist/launcher/subminer` | | `make install` | Install platform artifacts (wrapper, theme, AppImage/app bundle) | | `make install-plugin` | Install mpv Lua plugin and config | | `make deps` | Install JS dependencies (root + texthooker-ui) | @@ -128,17 +147,25 @@ Run `make help` for a full list of targets. Key ones: - Linux packaged desktop launches pass `--background` using electron-builder `build.linux.executableArgs` in `package.json`. - Prefer direct inline deps objects in `src/main/` modules for simple pass-through wiring. - Add a helper/adapter service only when it performs meaningful adaptation, validation, or reuse (not identity mapping). -- See [Architecture](/architecture) for the composition model and extension rules. ## Environment Variables -| Variable | Description | -| --------------------------------- | ---------------------------------------------------------- | -| `SUBMINER_APPIMAGE_PATH` | Override AppImage location for subminer script | -| `SUBMINER_BINARY_PATH` | Alias for `SUBMINER_APPIMAGE_PATH` | -| `SUBMINER_YT_SUBGEN_MODE` | Override `youtubeSubgen.mode` for launcher | -| `SUBMINER_WHISPER_BIN` | Override `youtubeSubgen.whisperBin` for launcher | -| `SUBMINER_WHISPER_MODEL` | Override `youtubeSubgen.whisperModel` for launcher | -| `SUBMINER_YT_SUBGEN_OUT_DIR` | Override generated subtitle output directory | -| `SUBMINER_YT_SUBGEN_AUDIO_FORMAT` | Override extraction format used for whisper fallback | -| `SUBMINER_YT_SUBGEN_KEEP_TEMP` | Set to `1` to keep temporary subtitle-generation workspace | +| Variable | Description | +| ---------------------------------- | ------------------------------------------------------------------------------- | +| `SUBMINER_APPIMAGE_PATH` | Override SubMiner app binary path for launcher playback commands | +| `SUBMINER_BINARY_PATH` | Alias for `SUBMINER_APPIMAGE_PATH` | +| `SUBMINER_ROFI_THEME` | Override rofi theme path for launcher picker | +| `SUBMINER_LOG_LEVEL` | Override app logger level (`debug`, `info`, `warn`, `error`) | +| `SUBMINER_MPV_LOG` | Override mpv/app shared log file path | +| `SUBMINER_YT_SUBGEN_MODE` | Override `youtubeSubgen.mode` for launcher | +| `SUBMINER_WHISPER_BIN` | Override `youtubeSubgen.whisperBin` for launcher | +| `SUBMINER_WHISPER_MODEL` | Override `youtubeSubgen.whisperModel` for launcher | +| `SUBMINER_YT_SUBGEN_OUT_DIR` | Override generated subtitle output directory | +| `SUBMINER_YT_SUBGEN_AUDIO_FORMAT` | Override extraction format used for whisper fallback | +| `SUBMINER_YT_SUBGEN_KEEP_TEMP` | Set to `1` to keep temporary subtitle-generation workspace | +| `SUBMINER_JIMAKU_API_KEY` | Override Jimaku API key for launcher subtitle downloads | +| `SUBMINER_JIMAKU_API_KEY_COMMAND` | Command used to resolve Jimaku API key at runtime | +| `SUBMINER_JIMAKU_API_BASE_URL` | Override Jimaku API base URL | +| `SUBMINER_JELLYFIN_ACCESS_TOKEN` | Override Jellyfin access token (used before stored encrypted session fallback) | +| `SUBMINER_JELLYFIN_USER_ID` | Optional Jellyfin user ID override | +| `SUBMINER_SKIP_MACOS_HELPER_BUILD` | Set to `1` to skip building the macOS helper binary during `bun run build` | diff --git a/docs/index.assets.test.ts b/docs/index.assets.test.ts new file mode 100644 index 0000000..d27bfd4 --- /dev/null +++ b/docs/index.assets.test.ts @@ -0,0 +1,14 @@ +import { expect, test } from 'bun:test'; +import { readFileSync } from 'node:fs'; + +const docsIndexPath = new URL('./index.md', import.meta.url); +const docsIndexContents = readFileSync(docsIndexPath, 'utf8'); + +test('docs demo media uses shared cache-busting asset version token', () => { + expect(docsIndexContents).toMatch(/const demoAssetVersion = ['"][^'"]+['"]/); + expect(docsIndexContents).toContain(':poster="`/assets/minecard-poster.jpg?v=${demoAssetVersion}`"'); + expect(docsIndexContents).toContain(''); + expect(docsIndexContents).toContain(''); + expect(docsIndexContents).toContain(''); + expect(docsIndexContents).toContain('SubMiner demo GIF fallback'); +}); diff --git a/docs/index.md b/docs/index.md index fb85fba..335d430 100644 --- a/docs/index.md +++ b/docs/index.md @@ -67,6 +67,10 @@ features: details: Stream subtitles in real time to browser tools via local WebSocket and keep your stack integrated. --- + +

How it fits together

@@ -102,11 +106,11 @@ features:

See it in action

Subtitles, lookup flow, and card enrichment from a real playback session.

- - SubMiner demo GIF fallback + + SubMiner demo GIF fallback
diff --git a/docs/public/assets/minecard-poster.jpg b/docs/public/assets/minecard-poster.jpg new file mode 100644 index 0000000..a1e8139 Binary files /dev/null and b/docs/public/assets/minecard-poster.jpg differ diff --git a/docs/subagents/INDEX.md b/docs/subagents/INDEX.md index 7782984..1a08d61 100644 --- a/docs/subagents/INDEX.md +++ b/docs/subagents/INDEX.md @@ -90,3 +90,7 @@ Read first. Keep concise. | `codex-overlay-three-window-layout-20260223T021606Z-9z2t` | `codex-overlay-three-window-layout` | `Implement top-anchored secondary subtitle overlay window (20%) plus swappable primary overlay region (80%).` | `handoff` | `docs/subagents/agents/codex-overlay-three-window-layout-20260223T021606Z-9z2t.md` | `2026-02-23T02:44:37Z` | | `opencode-task110-backlog-sync-20260223T025059Z-k3m7` | `opencode-task110-backlog-sync` | `Verify TASK-110 completion state and synchronize backlog metadata with plan-first workflow.` | `handoff` | `docs/subagents/agents/opencode-task110-backlog-sync-20260223T025059Z-k3m7.md` | `2026-02-23T02:53:30Z` | | `codex-docs-page-polish-20260223T025932Z-b7k2` | `codex-docs-page-polish` | `Polish docs landing page and sync public workflow docs with current overlay stack.` | `handoff` | `docs/subagents/agents/codex-docs-page-polish-20260223T025932Z-b7k2.md` | `2026-02-23T03:19:20Z` | +| `opencode-remove-maint-guardrails-20260223T033715Z-2a53` | `opencode-remove-maint-guardrails` | `Remove Maintainability Guardrails docs section and associated guardrail code/commands.` | `handoff` | `docs/subagents/agents/opencode-remove-maint-guardrails-20260223T033715Z-2a53.md` | `2026-02-23T03:40:20Z` | +| `codex-architecture-doc-refresh-20260223T033941Z-d6se` | `codex-architecture-doc-refresh` | `Review repository architecture surfaces and refresh docs/architecture.md content to match current code state.` | `handoff` | `docs/subagents/agents/codex-architecture-doc-refresh-20260223T033941Z-d6se.md` | `2026-02-23T03:44:17Z` | +| `codex-docs-video-thumb-cache-20260223T033929Z-k8p2` | `codex-docs-video-thumb-cache` | `Fix docs landing page demo video thumbnail staleness after direct asset replacement.` | `handoff` | `docs/subagents/agents/codex-docs-video-thumb-cache-20260223T033929Z-k8p2.md` | `2026-02-23T03:44:04Z` | +| `codex-development-docs-review-20260223T034520Z-2ebb` | `codex-development-docs-review` | `Review codebase and refresh docs/development.md to match current project state.` | `done` | `docs/subagents/agents/codex-development-docs-review-20260223T034520Z-2ebb.md` | `2026-02-23T03:49:16Z` | diff --git a/docs/subagents/agents/codex-architecture-doc-refresh-20260223T033941Z-d6se.md b/docs/subagents/agents/codex-architecture-doc-refresh-20260223T033941Z-d6se.md new file mode 100644 index 0000000..10301c2 --- /dev/null +++ b/docs/subagents/agents/codex-architecture-doc-refresh-20260223T033941Z-d6se.md @@ -0,0 +1,32 @@ +# Agent: `codex-architecture-doc-refresh-20260223T033941Z-d6se` + +- alias: `codex-architecture-doc-refresh` +- mission: `Review current runtime/module architecture and update docs/architecture.md content to match real code paths.` +- status: `handoff` +- branch: `main` +- started_at: `2026-02-23T03:39:41Z` +- heartbeat_minutes: `5` + +## Current Work (newest first) +- [2026-02-23T03:44:17Z] handoff: architecture docs refreshed to match current codebase structure/runtime ownership; docs build passed; ready for user review. +- [2026-02-23T03:44:17Z] test: `bun run docs:build` passed. +- [2026-02-23T03:44:17Z] progress: updated `docs/architecture.md` sections for project structure, service layer, renderer layering, lifecycle, composition conventions, and extension rules; mermaid blocks left unchanged. +- [2026-02-23T03:39:41Z] intent: refresh `docs/architecture.md` using direct repo evidence; keep diagrams untouched per user request. +- [2026-02-23T03:39:41Z] progress: loaded `docs/subagents/INDEX.md`, `docs/subagents/collaboration.md`, current `docs/architecture.md`, and source tree inventory. + +## Files Touched +- `docs/subagents/INDEX.md` +- `docs/subagents/collaboration.md` +- `docs/subagents/agents/codex-architecture-doc-refresh-20260223T033941Z-d6se.md` +- `backlog/tasks/task-113 - Refresh-architecture-doc-content-to-match-current-codebase.md` +- `docs/architecture.md` + +## Assumptions +- User wants content accuracy only; mermaid/flow diagrams intentionally left as-is. +- Existing uncommitted guardrail-removal changes are separate work; avoid touching those files. + +## Open Questions / Blockers +- None. + +## Next Step +- Await user follow-up; if requested, apply same drift pass to other docs pages (`docs/development.md`, `docs/mining-workflow.md`). diff --git a/docs/subagents/agents/codex-development-docs-review-20260223T034520Z-2ebb.md b/docs/subagents/agents/codex-development-docs-review-20260223T034520Z-2ebb.md new file mode 100644 index 0000000..26c4330 --- /dev/null +++ b/docs/subagents/agents/codex-development-docs-review-20260223T034520Z-2ebb.md @@ -0,0 +1,31 @@ +# Agent: `codex-development-docs-review-20260223T034520Z-2ebb` + +- alias: `codex-development-docs-review` +- mission: `Review codebase and refresh docs/development.md to match current project state.` +- status: `done` +- branch: `main` +- started_at: `2026-02-23T03:46:06Z` +- heartbeat_minutes: `5` + +## Current Work (newest first) +- [2026-02-23T03:49:16Z] handoff: refreshed `docs/development.md` for current setup/build/test/env workflow; validated with `bun run docs:build`; updated backlog ticket + subagent bookkeeping. +- [2026-02-23T03:48:30Z] test: `bun run docs:build` passed after docs edits (VitePress chunk-size warning only). +- [2026-02-23T03:47:40Z] progress: fixed setup drift (`pnpm` -> `bun`, added submodule init), aligned testing section with CI lanes, corrected subtitle test placeholder wording, expanded env vars to active launcher/runtime overrides. +- [2026-02-23T03:46:06Z] intent: initialize subagent+backlog bookkeeping, then audit `docs/development.md` against actual scripts/tests/runtime layout before editing docs. + +## Files Touched +- `docs/subagents/agents/codex-development-docs-review-20260223T034520Z-2ebb.md` +- `docs/subagents/INDEX.md` +- `docs/subagents/collaboration.md` +- `backlog/tasks/task-114 - Refresh-development-doc-content-to-match-current-codebase.md` +- `docs/development.md` + +## Assumptions +- `Backlog.md` is managed via `backlog/` markdown files in this repo; create a new task ticket for this request. +- Existing dirty worktree entries are from prior sessions; avoid touching unrelated lines/files. + +## Open Questions / Blockers +- None. + +## Next Step +- Await user review/follow-up scope. diff --git a/docs/subagents/agents/codex-docs-video-thumb-cache-20260223T033929Z-k8p2.md b/docs/subagents/agents/codex-docs-video-thumb-cache-20260223T033929Z-k8p2.md new file mode 100644 index 0000000..29a5ae0 --- /dev/null +++ b/docs/subagents/agents/codex-docs-video-thumb-cache-20260223T033929Z-k8p2.md @@ -0,0 +1,39 @@ +# Agent: `codex-docs-video-thumb-cache-20260223T033929Z-k8p2` + +- alias: `codex-docs-video-thumb-cache` +- mission: `Fix docs landing page demo video thumbnail staleness after direct asset replacement` +- status: `handoff` +- branch: `main` +- started_at: `2026-02-23T03:40:48Z` +- heartbeat_minutes: `5` + +## Current Work +- [2026-02-23T03:40:48Z] intent: confirm root cause for stale docs video thumbnail and apply minimal cache-busting/docs fix. +- [2026-02-23T03:40:48Z] plan: touch `docs/index.md`; add regression coverage if lightweight; validate with docs build/targeted test. +- [2026-02-23T03:40:48Z] assumption: stale thumbnail caused by static poster/source URLs reusing identical path after direct file replacement. +- [2026-02-23T03:42:25Z] progress: added failing regression test `docs/index.assets.test.ts` asserting shared cache-busting token across demo media URLs. +- [2026-02-23T03:42:58Z] progress: generated fresh poster from `docs/public/assets/minecard.webm` (`minecard-poster.jpg`) and wired docs video block to shared `demoAssetVersion` tokenized URLs. +- [2026-02-23T03:43:20Z] test: `bun test docs/index.assets.test.ts` passes (1/1). +- [2026-02-23T03:43:35Z] test: `bun run docs:build` passes. +- [2026-02-23T03:43:55Z] handoff: TASK-112 marked Done with implementation notes and validation commands. +- [2026-02-23T03:44:04Z] progress: regenerated `minecard-poster.jpg` from `minecard.webm` at exactly `00:00:12` and bumped `demoAssetVersion` to `20260223-2` to force refresh. +- [2026-02-23T03:44:04Z] test: reran `bun test docs/index.assets.test.ts` (pass). + +## Files Touched +- `docs/subagents/agents/codex-docs-video-thumb-cache-20260223T033929Z-k8p2.md` +- `docs/subagents/INDEX.md` +- `docs/subagents/collaboration.md` +- `backlog/tasks/task-112 - Fix-docs-demo-video-thumbnail-cache-staleness.md` +- `docs/index.assets.test.ts` +- `docs/index.md` +- `docs/public/assets/minecard-poster.jpg` + +## Assumptions +- Browser/CDN cache can keep prior media when URL path remains unchanged. +- Docs home video section in `docs/index.md` is the only requested scope. + +## Open Questions / Blockers +- None. + +## Next Step +- Share fix summary and ask user to hard-refresh docs page once (`Cmd+Shift+R`) to bypass local cache. diff --git a/docs/subagents/agents/opencode-remove-maint-guardrails-20260223T033715Z-2a53.md b/docs/subagents/agents/opencode-remove-maint-guardrails-20260223T033715Z-2a53.md new file mode 100644 index 0000000..cba0138 --- /dev/null +++ b/docs/subagents/agents/opencode-remove-maint-guardrails-20260223T033715Z-2a53.md @@ -0,0 +1,46 @@ +# Agent: `opencode-remove-maint-guardrails-20260223T033715Z-2a53` + +- alias: `opencode-remove-maint-guardrails` +- mission: `Remove Maintainability Guardrails docs section and associated guardrail code/commands.` +- status: `handoff` +- branch: `main` +- started_at: `2026-02-23T03:37:39Z` +- heartbeat_minutes: `5` + +## Current Work (newest first) + +- [2026-02-23T03:40:20Z] handoff: completed TASK-111; removed docs section, package scripts, CI guardrail step, and runtime-cycle/fan-in script code + fixtures; validation (`bun run tsc --noEmit`, `bun run docs:build`) passed. +- [2026-02-23T03:40:03Z] progress: removed `## Maintainability Guardrails` from `docs/development.md`, deleted `check:main-fanin*` and `check:runtime-cycles*` scripts from `package.json`, removed CI fail-fast guardrails step, and deleted associated scripts/fixtures under `scripts/`. +- [2026-02-23T03:37:39Z] intent: initialized session, linked backlog task TASK-111, and preparing scoped removal pass for maintainability guardrails docs and related code. +- [2026-02-23T03:37:39Z] assumptions: removal target is explicit "Maintainability Guardrails" section and direct command/code references tied to it. + +## Files Touched + +- `docs/subagents/INDEX.md` +- `docs/subagents/collaboration.md` +- `docs/subagents/agents/opencode-remove-maint-guardrails-20260223T033715Z-2a53.md` +- `backlog/tasks/task-111 - Remove-Maintainability-Guardrails-docs-section-and-related-guardrail-code.md` (via Backlog MCP) +- `docs/development.md` +- `package.json` +- `.github/workflows/ci.yml` +- `scripts/check-main-runtime-fanin.ts` (deleted) +- `scripts/check-runtime-cycles.ts` (deleted) +- `scripts/check-runtime-cycles.test.ts` (deleted) +- `scripts/fixtures/runtime-cycles/acyclic/entry.ts` (deleted) +- `scripts/fixtures/runtime-cycles/acyclic/feature.ts` (deleted) +- `scripts/fixtures/runtime-cycles/acyclic/utils/index.ts` (deleted) +- `scripts/fixtures/runtime-cycles/cyclic/module-a.ts` (deleted) +- `scripts/fixtures/runtime-cycles/cyclic/module-b.ts` (deleted) +- `scripts/fixtures/runtime-cycles/cyclic/nested/index.ts` (deleted) + +## Assumptions + +- Request targets current docs page section shown in screenshot and associated command/code paths, not unrelated guardrails. + +## Open Questions / Blockers + +- None. + +## Next Step + +- Await user follow-up (optional commit/changelog pass if requested). diff --git a/docs/subagents/collaboration.md b/docs/subagents/collaboration.md index 1013083..635193b 100644 --- a/docs/subagents/collaboration.md +++ b/docs/subagents/collaboration.md @@ -157,3 +157,12 @@ Shared notes. Append-only. - [2026-02-23T02:44:37Z] [codex-overlay-three-window-layout-20260223T021606Z-9z2t|codex-overlay-three-window-layout] backlog sync requested post-commit; updated TASK-110 `updated_date`, added commit reference (`b8f7d5e`), and added final summary block. - [2026-02-23T02:50:59Z] [opencode-task110-backlog-sync-20260223T025059Z-k3m7|opencode-task110-backlog-sync] starting TASK-110 closure verification pass via Backlog MCP + writing-plans/executing-plans workflow; scope backlog metadata validation/sync only unless missing evidence is found. - [2026-02-23T02:53:30Z] [opencode-task110-backlog-sync-20260223T025059Z-k3m7|opencode-task110-backlog-sync] completed verification/sync: recorded closure plan, revalidated commit/code evidence (parallel subagent audits), appended TASK-110 verification note, and confirmed task remains Done with all AC checked. +- [2026-02-23T03:37:39Z] [opencode-remove-maint-guardrails-20260223T033715Z-2a53|opencode-remove-maint-guardrails] starting TASK-111 removal pass: delete docs section "Maintainability Guardrails" and remove associated guardrail command/code references; scope docs/scripts/config only. +- [2026-02-23T03:40:20Z] [opencode-remove-maint-guardrails-20260223T033715Z-2a53|opencode-remove-maint-guardrails] completed TASK-111: removed maintainability guardrails docs section, deleted fan-in/runtime-cycle scripts + fixtures, removed related package scripts and CI step, validated via `bun run tsc --noEmit` and `bun run docs:build`. +- [2026-02-23T03:39:41Z] [codex-architecture-doc-refresh-20260223T033941Z-d6se|codex-architecture-doc-refresh] starting docs drift audit for `docs/architecture.md`; scope is content-only refresh vs current `src/**` architecture (no mermaid/chart edits), avoiding active guardrail-removal files. +- [2026-02-23T03:40:48Z] [codex-docs-video-thumb-cache-20260223T033929Z-k8p2|codex-docs-video-thumb-cache] starting docs bugfix for stale home demo thumbnail after direct video replacement; scope `docs/index.md` plus lightweight regression coverage/backlog linkage only. +- [2026-02-23T03:43:55Z] [codex-docs-video-thumb-cache-20260223T033929Z-k8p2|codex-docs-video-thumb-cache] completed TASK-112: generated `minecard-poster.jpg` from latest webm, switched docs demo media URLs to shared cache-busting token, added `docs/index.assets.test.ts`, and validated with `bun test docs/index.assets.test.ts` + `bun run docs:build`. +- [2026-02-23T03:44:04Z] [codex-docs-video-thumb-cache-20260223T033929Z-k8p2|codex-docs-video-thumb-cache] user follow-up applied: regenerated poster at exact `00:00:12` from `minecard.webm` and bumped docs asset token to `20260223-2` to force static thumbnail refresh. +- [2026-02-23T03:44:17Z] [codex-architecture-doc-refresh-20260223T033941Z-d6se|codex-architecture-doc-refresh] completed architecture drift pass: refreshed `docs/architecture.md` structure/service/composition/lifecycle content against current code (`src`, `launcher`, `plugin`), left mermaid sections untouched, and verified `bun run docs:build`; moved backlog linkage to `TASK-113` to avoid active `TASK-112` collision. +- [2026-02-23T03:46:06Z] [codex-development-docs-review-20260223T034520Z-2ebb|codex-development-docs-review] starting user-requested thorough codebase + `docs/development.md` drift audit; scope docs refresh + verification only, no runtime behavior changes expected. +- [2026-02-23T03:49:16Z] [codex-development-docs-review-20260223T034520Z-2ebb|codex-development-docs-review] completed `docs/development.md` refresh: setup/deps/submodule instructions corrected, CI-parity testing lane documented, placeholder subtitle test status clarified, Makefile reference adjusted, env variable table expanded to active launcher/runtime overrides; `bun run docs:build` passed.