mirror of
https://github.com/ksyasuda/SubMiner.git
synced 2026-02-27 18:22:41 -08:00
docs: refresh architecture and development docs
Update docs content to match current launcher/plugin/runtime structure and fix stale home demo media assets with cache-busted URLs plus poster refresh. Add supporting backlog/subagent tracking records and docs asset regression coverage.
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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` |
|
||||
|
||||
14
docs/index.assets.test.ts
Normal file
14
docs/index.assets.test.ts
Normal file
@@ -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('<source :src="`/assets/minecard.webm?v=${demoAssetVersion}`" type="video/webm" />');
|
||||
expect(docsIndexContents).toContain('<source :src="`/assets/minecard.mp4?v=${demoAssetVersion}`" type="video/mp4" />');
|
||||
expect(docsIndexContents).toContain('<a :href="`/assets/minecard.webm?v=${demoAssetVersion}`" target="_blank" rel="noreferrer">');
|
||||
expect(docsIndexContents).toContain('<img :src="`/assets/minecard.gif?v=${demoAssetVersion}`" alt="SubMiner demo GIF fallback" style="width: 100%; height: auto;" />');
|
||||
});
|
||||
@@ -67,6 +67,10 @@ features:
|
||||
details: Stream subtitles in real time to browser tools via local WebSocket and keep your stack integrated.
|
||||
---
|
||||
|
||||
<script setup>
|
||||
const demoAssetVersion = '20260223-2';
|
||||
</script>
|
||||
|
||||
<div class="landing-shell">
|
||||
<section class="workflow-section">
|
||||
<h2>How it fits together</h2>
|
||||
@@ -102,11 +106,11 @@ features:
|
||||
<section class="demo-section">
|
||||
<h2>See it in action</h2>
|
||||
<p>Subtitles, lookup flow, and card enrichment from a real playback session.</p>
|
||||
<video controls playsinline preload="metadata" poster="/assets/demo-poster.jpg">
|
||||
<source :src="'/assets/minecard.webm'" type="video/webm" />
|
||||
<source :src="'/assets/minecard.mp4'" type="video/mp4" />
|
||||
<a :href="'/assets/minecard.webm'" target="_blank" rel="noreferrer">
|
||||
<img :src="'/assets/minecard.gif'" alt="SubMiner demo GIF fallback" style="width: 100%; height: auto;" />
|
||||
<video controls playsinline preload="metadata" :poster="`/assets/minecard-poster.jpg?v=${demoAssetVersion}`">
|
||||
<source :src="`/assets/minecard.webm?v=${demoAssetVersion}`" type="video/webm" />
|
||||
<source :src="`/assets/minecard.mp4?v=${demoAssetVersion}`" type="video/mp4" />
|
||||
<a :href="`/assets/minecard.webm?v=${demoAssetVersion}`" target="_blank" rel="noreferrer">
|
||||
<img :src="`/assets/minecard.gif?v=${demoAssetVersion}`" alt="SubMiner demo GIF fallback" style="width: 100%; height: auto;" />
|
||||
</a>
|
||||
</video>
|
||||
</section>
|
||||
|
||||
BIN
docs/public/assets/minecard-poster.jpg
Normal file
BIN
docs/public/assets/minecard-poster.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 122 KiB |
@@ -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` |
|
||||
|
||||
@@ -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`).
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user