textflowkit 0.1.9__tar.gz → 0.1.10__tar.gz

{textflowkit-0.1.9 → textflowkit-0.1.10}/.github/workflows/ci.yml

@@ -90,6 +90,6 @@ jobs:
           python -m pip install "setuptools>=83" "build>=1.2"
           python -m build --wheel
           python -m build --wheel --outdir dist packages/textflowkit-fonts
-      - name: Smoke all three installed entry points
+      - name: Smoke all four installed entry points (CLI, MCP, HTTP, served UI)
         shell: bash
         run: python scripts/smoke_installed_wheel.py dist/textflowkit-*.whl dist/textflowkit_fonts-*.whl

{textflowkit-0.1.9 → textflowkit-0.1.10}/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## v0.1.10 — 2026-10-06
+
+**The local browser interface ships.** The loopback-only browser workspace
+(`textflowkit-ui`) is now part of the core package rather than source-only, so a
+regular install of this release carries the command. Core version: 0.1.10;
+unchanged optional fonts: 0.1.6.
+
+### Added
+
+- **Local browser interface in the core package.** `textflowkit-ui` serves a
+  point-and-click workspace on **this machine only**: it binds `127.0.0.1` (never
+  off the machine, whatever `TEXTFLOWKIT_ALLOW_REMOTE` is set to) and opens a
+  browser once serving. It mounts the existing developer HTTP app under `/api`
+  **unchanged** — the same routes, submission contract, and job store — and adds
+  only transport: a loopback session layer, a streamed upload, a fixed-format
+  download, in-workspace playback, and a capability endpoint. It adds **no new
+  dependency** beyond the existing `http` extra (FastAPI + uvicorn).
+- **Durable jobs, cancel and resume in the workspace.** Jobs and checkpoints are
+  stored durably under the per-user data directory unless
+  `TEXTFLOWKIT_DB` / `TEXTFLOWKIT_WORK_ROOT` / `TEXTFLOWKIT_OUTPUT_ROOT` is set.
+  A dropped file is streamed and capped at **2 GiB** by default
+  (`TEXTFLOWKIT_UI_MAX_UPLOAD_BYTES` overrides it). A running job can be
+  cancelled, and a durable job resumed.
+- **Windows desktop shortcut.** `textflowkit-ui --create-shortcut` creates a Start
+  Menu entry that launches with `pythonw` (no console) and needs no `pywin32`.
+  Under `pythonw` a startup failure is logged under the per-user data directory
+  and shown in a message box rather than failing silently.
+- **Controlled shutdown that drains.** **Stop server** asks this process's own
+  uvicorn server to exit through its supported `should_exit` flag; the normal
+  lifespan teardown **waits for current jobs to finish** before draining the
+  worker pool rather than interrupting them, so a running job's saved progress
+  survives and is resumable. It never sends a signal to a pid.
+
+### Changed
+
+- **Documentation surfaces.** README, user manual, install notes, developer
+  manual, architecture guide, roadmap, release checklist, site deployment, the
+  landing page, and the checked-in SVG diagrams now describe the local browser
+  interface as a shipped feature and a fifth door, and remove the earlier
+  "unreleased candidate / install from source only" wording.
+- **No endpoint-breaking change.** The CLI, Python API, MCP server, and JSON HTTP
+  adapter are unchanged in this release; the optional engines, diarization, and
+  translation keep their documented dependency requirements.
+
+### Verification boundary
+
+Automated coverage runs the UI's routes, packaging, ownership/shutdown, and
+security boundaries. A **native Windows** machine, in a real browser, proved the
+workspace end to end (drop a file, submit, download, stop). That is one platform's
+browser proof, **not** a live Linux or macOS UI run — those platforms are covered
+by automated tests only, and cross-platform CI (Windows/Linux/macOS) is a separate
+step run by the coordinator. **No live optional-backend (translation or
+diarization) run through the UI is claimed.** The engine and packaging changes of
+v0.1.9 are unchanged by this release.
+
 ## v0.1.9 — 2026-10-05
 
 **Whistle is now the default engine.** This release ships the Whistle integration

{textflowkit-0.1.9 → textflowkit-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: textflowkit
-Version: 0.1.9
+Version: 0.1.10
 Summary: Cross-platform media transcription toolkit: URL or file in, timestamped transcripts and subtitle files out.
 Project-URL: Homepage, https://www.textflowkit.org/
 Project-URL: Issues, https://github.com/scottconverse/textflowkit/issues
@@ -67,7 +67,7 @@ Cross-platform media transcription toolkit. **One core, one CLI, thin adapters.*
 [User manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md) ·
 [Developer and integration manual](https://github.com/scottconverse/textflowkit/blob/main/docs/adapters.md)
 
-**Current release: [v0.1.9](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.9).**
+**Current release: [v0.1.10](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.10).**
 
 The [static site deployment](https://github.com/scottconverse/textflowkit/blob/main/docs/site-deployment.md) is hosted on Cloudflare
 Pages. GitHub remains the source and CI host; the website does not run the
@@ -128,10 +128,11 @@ DOCX and PDF are available through the optional `export` extra.
 
 ## Architecture
 
-![TextFlowKit shared-core architecture: four thin entry points (CLI, Python, MCP, HTTP) feed one core that acquires and decodes media, transcribes with the default Whistle engine or an explicitly selected openai-whisper, keeps job state and resume checkpoints in an optional SQLite store, adds optional speaker or translation postprocessing, and publishes TXT, SRT, VTT, JSON, Markdown, and optional DOCX/PDF exports.](https://raw.githubusercontent.com/scottconverse/textflowkit/v0.1.9/docs/assets/architecture-overview.svg)
+![TextFlowKit shared-core architecture: five thin entry points feed one core. The CLI, Python API, MCP, HTTP API, and the local browser UI (a fifth door that mounts the existing HTTP app under /api and shares the same job store, adding transport only, not a new pipeline) sit above one core that acquires and decodes media, transcribes with the default Whistle engine or an explicitly selected openai-whisper, keeps job state and resume checkpoints in an optional SQLite store, adds optional speaker or translation postprocessing, and publishes TXT, SRT, VTT, JSON, Markdown, and optional DOCX/PDF exports.](https://raw.githubusercontent.com/scottconverse/textflowkit/v0.1.10/docs/assets/architecture-overview.svg)
 
-The design principle is **one engine, three doors**. Everything of substance lives in
-the core; the interfaces are thin.
+The design principle is **one shared core, thin doors**. Everything of substance
+lives in the core; the interfaces are thin — the local browser UI is a fifth door
+that adds only transport over the existing HTTP app and shared job store.
 
 | Layer | Path | Responsibility |
 |---|---|---|
@@ -141,6 +142,7 @@ the core; the interfaces are thin.
 | **CLI** | `src/textflowkit/cli.py` | Reference interface (subprocess-friendly) |
 | **MCP** | `src/textflowkit/adapters/mcp_server.py` | stdio + Streamable HTTP, for AI harnesses |
 | **HTTP** | `src/textflowkit/adapters/http_server.py` | JSON API, for software products and web frontends |
+| **Local UI** | `src/textflowkit/ui` | Loopback-only browser workspace over the same HTTP app and job store |
 
 Because the core owns the pipeline, adding a door is cheap — and adding a platform
 means writing one source adapter, not another tool.
@@ -294,7 +296,7 @@ textflowkit export ./transcript.json --format vtt
 needs no PyTorch, so a fresh `pip install textflowkit` stays small and pulls no
 torch; `openai-whisper` is an explicitly selectable opt-in engine.
 
-![Whistle bounded block run and durable resume: a decoded PCM WAV is split into 26-second cores with up to 2 seconds of context (each clip ≤ 30 s), each core runs as one owned child with forced telemetry-off flags, a partial checkpoint is written after each core, and a resume validates the source and decoded-WAV hashes then re-runs only the unfinished cores.](https://raw.githubusercontent.com/scottconverse/textflowkit/v0.1.9/docs/assets/whistle-resume.svg)
+![Whistle bounded block run and durable resume: a decoded PCM WAV is split into 26-second cores with up to 2 seconds of context (each clip ≤ 30 s), each core runs as one owned child with forced telemetry-off flags, a partial checkpoint is written after each core, and a resume validates the source and decoded-WAV hashes then re-runs only the unfinished cores.](https://raw.githubusercontent.com/scottconverse/textflowkit/v0.1.10/docs/assets/whistle-resume.svg)
 
 - **CPU only, no torch.** It runs a pinned native binary and downloads one pinned
   model on first use. Naming a GPU device is refused rather than silently
@@ -397,6 +399,66 @@ contract checks cover it, and running an actual build is deliberately out of
 scope here, so no image is claimed to build or start. See
 [the container example](https://github.com/scottconverse/textflowkit/blob/main/docs/adapters.md#container-example-dockerfile-and-compose).
 
+## Local browser interface
+
+For point-and-click use there is a local browser workspace that runs on **this
+machine only**, reuses the same pipeline and job store, and adds no dependency of
+its own beyond the `http` extra. It ships with the core package as of v0.1.10:
+a regular install of the current release carries it.
+
+```bash
+python -m pip install 'textflowkit[http,export]==0.1.10'
+textflowkit-ui
+```
+
+On Windows you can create a desktop shortcut when you want one:
+
+```powershell
+textflowkit-ui --create-shortcut                 # Start Menu entry (pythonw, no console)
+textflowkit-ui --create-shortcut --shortcut-dir 'C:\path\to\folder'
+```
+
+The shortcut is created only on request and needs no `pywin32`. Under `pythonw`
+there is no console, so a startup failure is written to a log file under the
+per-user data directory and shown in a message box rather than failing silently.
+The normal operator path is to launch from that shortcut; the console command
+above is equivalent.
+
+**This is a local app, not a public website.** The [landing page](https://www.textflowkit.org/)
+is static documentation served by Cloudflare Pages; it does **not** run the
+transcription engine and offers no upload form. The browser workspace exists only
+on the machine that installed it.
+
+- **Loopback only.** It binds `127.0.0.1` (never off the machine, whatever
+  `TEXTFLOWKIT_ALLOW_REMOTE` is set to) and opens a browser once it is serving.
+- **One owner per database.** A second launch against the same database opens the
+  UI already running rather than starting a competing server. **Stop server** in
+  the workspace shuts the local server down without a terminal, waiting for the
+  current jobs to finish rather than interrupting them. Shutdown **drains** — it
+  lets in-flight jobs complete; it does **not** auto-cancel them. Cancel a job
+  first to stop it early.
+- **Durable jobs with cancel and resume.** Jobs and checkpoints are stored
+  durably under the per-user data directory unless you set `TEXTFLOWKIT_DB` /
+  `TEXTFLOWKIT_WORK_ROOT` / `TEXTFLOWKIT_OUTPUT_ROOT`. A dropped file is capped
+  at **2 GiB** by default (`TEXTFLOWKIT_UI_MAX_UPLOAD_BYTES` overrides it).
+  In-workspace playback uses the browser's native player on the **currently
+  selected** media, so it depends on what that browser can decode; it is a
+  convenience preview, not a format guarantee.
+- **No UI analytics.** The page loads no CDN asset and no analytics, and the
+  session token lives only in the page — never in a URL, cookie, or log line.
+- **What uses the network.** The page itself loads nothing remote. A **URL
+  source** is downloaded from the internet; an engine's **model** may be
+  downloaded on first use; and **remote or cloud translation** (an advanced
+  option) sends transcript text to that backend. With local media and a local
+  translation model, no transcript leaves the machine.
+- `--port`, `--no-browser`, and `--version` are available.
+
+The other doors are unchanged: the CLI, Python API, MCP, and HTTP adapters keep
+their existing behavior, and the optional engines, diarization, and translation
+retain their documented dependency requirements. See the
+[user manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md#7-local-browser-interface)
+and [architecture guide](https://github.com/scottconverse/textflowkit/blob/main/docs/architecture.md#one-owner-per-database).
+
 ## Durable, bounded, cancellable
 
 ```bash
@@ -411,23 +473,38 @@ boundary. See [docs/adapters.md](https://github.com/scottconverse/textflowkit/bl
 
 The MCP and HTTP adapters are **job-based**: submission returns a job id
 immediately and clients poll for completion. The CLI uses the same core but
-waits for the result. This lets AI harnesses, software products, and a future
-web frontend share the job contract without blocking a request.
+waits for the result. This lets AI harnesses, software products, and the local
+browser interface share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.9 release.** Core, CLI, MCP, and HTTP have automated
-coverage. This release makes **Whistle the default engine** — a native CPU-only
-transcriber that needs no PyTorch — and moves `openai-whisper` to the optional
-`whisper` extra, selected explicitly with `--engine whisper` or
+**v0.1.10 release.** Core, CLI, MCP, HTTP, and the local browser interface have
+automated coverage. This release **ships the local browser interface**
+(`textflowkit-ui`) in the core package: a loopback-only workspace that reuses the
+same pipeline, submission contract, and job store, with a durable store, cancel
+and resume, and a Windows desktop shortcut (`textflowkit-ui --create-shortcut`).
+It adds **no new dependency** beyond the existing `http` extra, so a regular
+`pip install 'textflowkit[http,export]==0.1.10'` carries it. The engine, CLI,
+Python, MCP, and HTTP surfaces are unchanged and there is **no endpoint-breaking
+change**. It builds on v0.1.9, which made **Whistle the default engine** — a
+native CPU-only transcriber that needs no PyTorch — and moved `openai-whisper` to
+the optional `whisper` extra, selected explicitly with `--engine whisper` or
 `engine="whisper"`. Legacy engine aliases are preserved, so older saved jobs and
 `transcribe()` calls still decode. Whistle refuses an unsupported platform,
-language, or GPU request instead of silently falling back. Its engine's
+language, or GPU request instead of silently falling back; its engine's
 verification boundary is in [Whistle (default engine)](#whistle-default-engine)
-above. Release publication uses the tag workflow, which requires successful
-exact-commit main CI before PyPI uploads and creates the public GitHub release
-only afterward. Check the linked release for artifacts and workflow status; local
-source verification is not a fresh PyPI-install or individual-harness receipt.
+above.
+
+**Verification limit.** The local browser interface is covered by an automated
+suite, and the UI's behavior was proved on a **native Windows** machine in a real
+browser. No live optional-backend (translation/diarization) run through the UI is
+claimed, and **no live Linux or macOS UI run was performed here** — those
+platforms are covered by automated tests only, and CI across Windows, Linux, and
+macOS is the coordinator's separate step. Release publication uses the tag
+workflow, which requires successful exact-commit main CI before PyPI uploads and
+creates the public GitHub release only afterward. Check the linked release for
+artifacts and workflow status; local source verification is not a fresh
+PyPI-install or individual-harness receipt.
 
 The v0.1.8 release carried four fixes for the 2026-10-01 post-release audit-lite
 (findings AL-001 – AL-004): CLI owning-process startup recovery so an interrupted
@@ -439,8 +516,8 @@ that precede it. The v0.1.7 source candidate was verified with real CLI, HTTP an
 MCP speech, seven-format exports and completed resume; the v0.1.8 runtime fixes
 were independently checked through fresh-process CLI restart probes, real SQLite
 setup-failure tests, and the full Windows test suite. Those checks are not new
-individual-harness receipts. That is the previous release's record, not evidence
-for v0.1.9.
+individual-harness receipts. That is the previous releases' record, not evidence
+for v0.1.10.
 
 The v0.1.6 release was the post-v0.1.5 review repair set: security hardening
 for media acquisition and the HTTP and MCP adapters, safer subtitle wrapping and
@@ -459,7 +536,7 @@ and both [core](https://pypi.org/project/textflowkit/0.1.6/) and
 [fonts](https://pypi.org/project/textflowkit-fonts/0.1.6/) PyPI projects are
 live — that is the v0.1.6 release's evidence, not a receipt for a later release.
 Everything from here to the end of this section is the v0.1.6 release's
-historical record as published: it is not re-verified for v0.1.9, whose separate release evidence is not supplied by these historical paragraphs.
+historical record as published: it is not re-verified for v0.1.10, whose separate release evidence is not supplied by these historical paragraphs.
 Merged-main CI passed 16/16 on the tagged commit; the published wheel and
 sdist digests match the GitHub release assets and their SHA-256 list; and a fresh
 Windows Python 3.12 install of `textflowkit[export,mcp,http]==0.1.6` from PyPI

{textflowkit-0.1.9 → textflowkit-0.1.10}/README.md

@@ -8,7 +8,7 @@ Cross-platform media transcription toolkit. **One core, one CLI, thin adapters.*
 [User manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md) ·
 [Developer and integration manual](https://github.com/scottconverse/textflowkit/blob/main/docs/adapters.md)
 
-**Current release: [v0.1.9](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.9).**
+**Current release: [v0.1.10](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.10).**
 
 The [static site deployment](https://github.com/scottconverse/textflowkit/blob/main/docs/site-deployment.md) is hosted on Cloudflare
 Pages. GitHub remains the source and CI host; the website does not run the
@@ -69,10 +69,11 @@ DOCX and PDF are available through the optional `export` extra.
 
 ## Architecture
 
-![TextFlowKit shared-core architecture: four thin entry points (CLI, Python, MCP, HTTP) feed one core that acquires and decodes media, transcribes with the default Whistle engine or an explicitly selected openai-whisper, keeps job state and resume checkpoints in an optional SQLite store, adds optional speaker or translation postprocessing, and publishes TXT, SRT, VTT, JSON, Markdown, and optional DOCX/PDF exports.](https://raw.githubusercontent.com/scottconverse/textflowkit/v0.1.9/docs/assets/architecture-overview.svg)
+![TextFlowKit shared-core architecture: five thin entry points feed one core. The CLI, Python API, MCP, HTTP API, and the local browser UI (a fifth door that mounts the existing HTTP app under /api and shares the same job store, adding transport only, not a new pipeline) sit above one core that acquires and decodes media, transcribes with the default Whistle engine or an explicitly selected openai-whisper, keeps job state and resume checkpoints in an optional SQLite store, adds optional speaker or translation postprocessing, and publishes TXT, SRT, VTT, JSON, Markdown, and optional DOCX/PDF exports.](https://raw.githubusercontent.com/scottconverse/textflowkit/v0.1.10/docs/assets/architecture-overview.svg)
 
-The design principle is **one engine, three doors**. Everything of substance lives in
-the core; the interfaces are thin.
+The design principle is **one shared core, thin doors**. Everything of substance
+lives in the core; the interfaces are thin — the local browser UI is a fifth door
+that adds only transport over the existing HTTP app and shared job store.
 
 | Layer | Path | Responsibility |
 |---|---|---|
@@ -82,6 +83,7 @@ the core; the interfaces are thin.
 | **CLI** | `src/textflowkit/cli.py` | Reference interface (subprocess-friendly) |
 | **MCP** | `src/textflowkit/adapters/mcp_server.py` | stdio + Streamable HTTP, for AI harnesses |
 | **HTTP** | `src/textflowkit/adapters/http_server.py` | JSON API, for software products and web frontends |
+| **Local UI** | `src/textflowkit/ui` | Loopback-only browser workspace over the same HTTP app and job store |
 
 Because the core owns the pipeline, adding a door is cheap — and adding a platform
 means writing one source adapter, not another tool.
@@ -235,7 +237,7 @@ textflowkit export ./transcript.json --format vtt
 needs no PyTorch, so a fresh `pip install textflowkit` stays small and pulls no
 torch; `openai-whisper` is an explicitly selectable opt-in engine.
 
-![Whistle bounded block run and durable resume: a decoded PCM WAV is split into 26-second cores with up to 2 seconds of context (each clip ≤ 30 s), each core runs as one owned child with forced telemetry-off flags, a partial checkpoint is written after each core, and a resume validates the source and decoded-WAV hashes then re-runs only the unfinished cores.](https://raw.githubusercontent.com/scottconverse/textflowkit/v0.1.9/docs/assets/whistle-resume.svg)
+![Whistle bounded block run and durable resume: a decoded PCM WAV is split into 26-second cores with up to 2 seconds of context (each clip ≤ 30 s), each core runs as one owned child with forced telemetry-off flags, a partial checkpoint is written after each core, and a resume validates the source and decoded-WAV hashes then re-runs only the unfinished cores.](https://raw.githubusercontent.com/scottconverse/textflowkit/v0.1.10/docs/assets/whistle-resume.svg)
 
 - **CPU only, no torch.** It runs a pinned native binary and downloads one pinned
   model on first use. Naming a GPU device is refused rather than silently
@@ -338,6 +340,66 @@ contract checks cover it, and running an actual build is deliberately out of
 scope here, so no image is claimed to build or start. See
 [the container example](https://github.com/scottconverse/textflowkit/blob/main/docs/adapters.md#container-example-dockerfile-and-compose).
 
+## Local browser interface
+
+For point-and-click use there is a local browser workspace that runs on **this
+machine only**, reuses the same pipeline and job store, and adds no dependency of
+its own beyond the `http` extra. It ships with the core package as of v0.1.10:
+a regular install of the current release carries it.
+
+```bash
+python -m pip install 'textflowkit[http,export]==0.1.10'
+textflowkit-ui
+```
+
+On Windows you can create a desktop shortcut when you want one:
+
+```powershell
+textflowkit-ui --create-shortcut                 # Start Menu entry (pythonw, no console)
+textflowkit-ui --create-shortcut --shortcut-dir 'C:\path\to\folder'
+```
+
+The shortcut is created only on request and needs no `pywin32`. Under `pythonw`
+there is no console, so a startup failure is written to a log file under the
+per-user data directory and shown in a message box rather than failing silently.
+The normal operator path is to launch from that shortcut; the console command
+above is equivalent.
+
+**This is a local app, not a public website.** The [landing page](https://www.textflowkit.org/)
+is static documentation served by Cloudflare Pages; it does **not** run the
+transcription engine and offers no upload form. The browser workspace exists only
+on the machine that installed it.
+
+- **Loopback only.** It binds `127.0.0.1` (never off the machine, whatever
+  `TEXTFLOWKIT_ALLOW_REMOTE` is set to) and opens a browser once it is serving.
+- **One owner per database.** A second launch against the same database opens the
+  UI already running rather than starting a competing server. **Stop server** in
+  the workspace shuts the local server down without a terminal, waiting for the
+  current jobs to finish rather than interrupting them. Shutdown **drains** — it
+  lets in-flight jobs complete; it does **not** auto-cancel them. Cancel a job
+  first to stop it early.
+- **Durable jobs with cancel and resume.** Jobs and checkpoints are stored
+  durably under the per-user data directory unless you set `TEXTFLOWKIT_DB` /
+  `TEXTFLOWKIT_WORK_ROOT` / `TEXTFLOWKIT_OUTPUT_ROOT`. A dropped file is capped
+  at **2 GiB** by default (`TEXTFLOWKIT_UI_MAX_UPLOAD_BYTES` overrides it).
+  In-workspace playback uses the browser's native player on the **currently
+  selected** media, so it depends on what that browser can decode; it is a
+  convenience preview, not a format guarantee.
+- **No UI analytics.** The page loads no CDN asset and no analytics, and the
+  session token lives only in the page — never in a URL, cookie, or log line.
+- **What uses the network.** The page itself loads nothing remote. A **URL
+  source** is downloaded from the internet; an engine's **model** may be
+  downloaded on first use; and **remote or cloud translation** (an advanced
+  option) sends transcript text to that backend. With local media and a local
+  translation model, no transcript leaves the machine.
+- `--port`, `--no-browser`, and `--version` are available.
+
+The other doors are unchanged: the CLI, Python API, MCP, and HTTP adapters keep
+their existing behavior, and the optional engines, diarization, and translation
+retain their documented dependency requirements. See the
+[user manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md#7-local-browser-interface)
+and [architecture guide](https://github.com/scottconverse/textflowkit/blob/main/docs/architecture.md#one-owner-per-database).
+
 ## Durable, bounded, cancellable
 
 ```bash
@@ -352,23 +414,38 @@ boundary. See [docs/adapters.md](https://github.com/scottconverse/textflowkit/bl
 
 The MCP and HTTP adapters are **job-based**: submission returns a job id
 immediately and clients poll for completion. The CLI uses the same core but
-waits for the result. This lets AI harnesses, software products, and a future
-web frontend share the job contract without blocking a request.
+waits for the result. This lets AI harnesses, software products, and the local
+browser interface share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.9 release.** Core, CLI, MCP, and HTTP have automated
-coverage. This release makes **Whistle the default engine** — a native CPU-only
-transcriber that needs no PyTorch — and moves `openai-whisper` to the optional
-`whisper` extra, selected explicitly with `--engine whisper` or
+**v0.1.10 release.** Core, CLI, MCP, HTTP, and the local browser interface have
+automated coverage. This release **ships the local browser interface**
+(`textflowkit-ui`) in the core package: a loopback-only workspace that reuses the
+same pipeline, submission contract, and job store, with a durable store, cancel
+and resume, and a Windows desktop shortcut (`textflowkit-ui --create-shortcut`).
+It adds **no new dependency** beyond the existing `http` extra, so a regular
+`pip install 'textflowkit[http,export]==0.1.10'` carries it. The engine, CLI,
+Python, MCP, and HTTP surfaces are unchanged and there is **no endpoint-breaking
+change**. It builds on v0.1.9, which made **Whistle the default engine** — a
+native CPU-only transcriber that needs no PyTorch — and moved `openai-whisper` to
+the optional `whisper` extra, selected explicitly with `--engine whisper` or
 `engine="whisper"`. Legacy engine aliases are preserved, so older saved jobs and
 `transcribe()` calls still decode. Whistle refuses an unsupported platform,
-language, or GPU request instead of silently falling back. Its engine's
+language, or GPU request instead of silently falling back; its engine's
 verification boundary is in [Whistle (default engine)](#whistle-default-engine)
-above. Release publication uses the tag workflow, which requires successful
-exact-commit main CI before PyPI uploads and creates the public GitHub release
-only afterward. Check the linked release for artifacts and workflow status; local
-source verification is not a fresh PyPI-install or individual-harness receipt.
+above.
+
+**Verification limit.** The local browser interface is covered by an automated
+suite, and the UI's behavior was proved on a **native Windows** machine in a real
+browser. No live optional-backend (translation/diarization) run through the UI is
+claimed, and **no live Linux or macOS UI run was performed here** — those
+platforms are covered by automated tests only, and CI across Windows, Linux, and
+macOS is the coordinator's separate step. Release publication uses the tag
+workflow, which requires successful exact-commit main CI before PyPI uploads and
+creates the public GitHub release only afterward. Check the linked release for
+artifacts and workflow status; local source verification is not a fresh
+PyPI-install or individual-harness receipt.
 
 The v0.1.8 release carried four fixes for the 2026-10-01 post-release audit-lite
 (findings AL-001 – AL-004): CLI owning-process startup recovery so an interrupted
@@ -380,8 +457,8 @@ that precede it. The v0.1.7 source candidate was verified with real CLI, HTTP an
 MCP speech, seven-format exports and completed resume; the v0.1.8 runtime fixes
 were independently checked through fresh-process CLI restart probes, real SQLite
 setup-failure tests, and the full Windows test suite. Those checks are not new
-individual-harness receipts. That is the previous release's record, not evidence
-for v0.1.9.
+individual-harness receipts. That is the previous releases' record, not evidence
+for v0.1.10.
 
 The v0.1.6 release was the post-v0.1.5 review repair set: security hardening
 for media acquisition and the HTTP and MCP adapters, safer subtitle wrapping and
@@ -400,7 +477,7 @@ and both [core](https://pypi.org/project/textflowkit/0.1.6/) and
 [fonts](https://pypi.org/project/textflowkit-fonts/0.1.6/) PyPI projects are
 live — that is the v0.1.6 release's evidence, not a receipt for a later release.
 Everything from here to the end of this section is the v0.1.6 release's
-historical record as published: it is not re-verified for v0.1.9, whose separate release evidence is not supplied by these historical paragraphs.
+historical record as published: it is not re-verified for v0.1.10, whose separate release evidence is not supplied by these historical paragraphs.
 Merged-main CI passed 16/16 on the tagged commit; the published wheel and
 sdist digests match the GitHub release assets and their SHA-256 list; and a fresh
 Windows Python 3.12 install of `textflowkit[export,mcp,http]==0.1.6` from PyPI

{textflowkit-0.1.9 → textflowkit-0.1.10}/docs/adapters.md

@@ -1,15 +1,16 @@
 # Developer and integration manual
 
-Current release: [v0.1.9](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.9).
+Current release: [v0.1.10](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.10).
 Start with the [user manual](user-manual.md) for everyday use. Harness versions
 in the compatibility table below identify **historical test sessions**, not
 the version of TextFlowKit currently published.
 
 textflowkit has one core and several thin doors. Nothing is duplicated between
-them: the CLI, the MCP server, and the HTTP API all call
-`textflowkit.core.submission` and share one job model.
+them: the CLI, the MCP server, the HTTP API, and the local browser
+interface (`textflowkit-ui`) all call `textflowkit.core.submission` and share one
+job model.
 
-![TextFlowKit shared-core architecture: four thin entry points (CLI, Python, MCP, HTTP) feed one core that acquires and decodes media, transcribes with the default Whistle engine or an explicitly selected openai-whisper, keeps job state and resume checkpoints in an optional SQLite store, adds optional speaker or translation postprocessing, and publishes TXT, SRT, VTT, JSON, Markdown, and optional DOCX/PDF exports.](assets/architecture-overview.svg)
+![TextFlowKit shared-core architecture: five thin entry points feed one core. The CLI, Python API, MCP, HTTP API, and the local browser UI (a fifth door that mounts the existing HTTP app under /api and shares the same job store, adding transport only, not a new pipeline) sit above one core that acquires and decodes media, transcribes with the default Whistle engine or an explicitly selected openai-whisper, keeps job state and resume checkpoints in an optional SQLite store, adds optional speaker or translation postprocessing, and publishes TXT, SRT, VTT, JSON, Markdown, and optional DOCX/PDF exports.](assets/architecture-overview.svg)
 
 ```
                     ┌──────────────────────┐
@@ -505,6 +506,77 @@ agree. So if you do leave it on, put it behind a proxy that appends its own
 observation rather than forwarding the caller's header, and keep
 `FORWARDED_ALLOW_IPS` narrow.
 
+## Local browser interface (`textflowkit-ui`)
+
+`textflowkit-ui` is a fourth thin door beside the CLI, MCP, and HTTP entry
+points. It mounts the developer HTTP app (`adapters.http_server`) under `/api`
+**unchanged** - the same routes, the same submission contract, the same job
+store - and adds only transport: a loopback-only browser session layer, a
+streamed upload, a fixed-format download, and a capability endpoint. It
+**ships in the core package as of v0.1.10** (it needs the `http` extra, which
+supplies FastAPI and uvicorn, and adds no new dependency). It has no public site
+of its own: it is a local app, not a hosted service.
+
+```bash
+python -m pip install 'textflowkit[http,export]==0.1.10'
+textflowkit-ui                 # serve on 127.0.0.1 and open a browser
+textflowkit-ui --no-browser --port 8901
+```
+
+![TextFlowKit local browser interface request flow: the operator opens the workspace from a desktop shortcut or the textflowkit-ui command, which launches a loopback-only server on 127.0.0.1 that holds an exclusive owner lock on the durable SQLite database; the operator drops a file or pastes a URL, a file is streamed to a per-user upload folder capped at 2 GiB by default; both become a submission through the same shared submission contract the CLI, MCP, and HTTP doors use, writing a durable job that runs through the shared core (Whistle by default or an explicit optional engine) decoding with ffmpeg and transcribing on this machine; a finished transcript is searchable, copyable, downloadable in a fixed format list, and playable with the browser's native player on the currently selected media.](assets/local-ui-flow.svg)
+
+Because it is a browser door and not a product, its rules are **stricter** than
+the developer HTTP app's:
+
+- **Loopback only, always.** It binds `127.0.0.1` and refuses any non-loopback
+  host, and it does **not** honour `TEXTFLOWKIT_ALLOW_REMOTE` - that opt-in widens
+  the developer API, and an unauthenticated browser interface must not be
+  reachable off the machine.
+- **A session capability on every mutator.** The shell embeds a per-process
+  random token in a `<meta>` element; every POST carries it in
+  `x-textflowkit-ui-capability`. A request must also pass a loopback host, a
+  provably-loopback peer, and an `Origin` that is *exactly* this UI's own origin.
+  The token never appears in a URL, a cookie, or a log line.
+- **No external asset, no telemetry.** The shell and its CSS/JS are served from
+  the package; the page loads no CDN script and no analytics. (`/ui/capabilities`
+  reports what the install can do without loading a model or downloading
+  anything.) Network *is* used for a URL source, an engine's first-use model
+  download, and a remote/cloud translation backend - see the translation caveat
+  [above](#translation): a `:cloud` model or a remote `TEXTFLOWKIT_OLLAMA_HOST`
+  sends transcript text to that host. Local media and a local translation model
+  keep transcripts on the machine.
+
+### One owner per database
+
+The UI runs startup recovery and the worker pool, so a store is owned by one UI
+process. It takes an **operating-system file lock** (`msvcrt` on Windows, `flock`
+on POSIX) on a persistent sibling of the database, keyed by the *resolved* path,
+*before* recovery runs. The kernel holds the lock for the live holder and releases
+it on exit **or crash**, so a killed run never blocks the next launch. A second
+launch discovers the running instance's loopback URL from a small record beside
+the lock and opens that instead of starting a competing server. Ownership is
+proved by the held lock plus a matching record - never by signalling or inspecting
+a pid. The same rule as every door still applies: **do not point two processes at
+one database file.** See the [architecture guide](architecture.md#one-owner-per-database).
+
+### Uploads and downloads
+
+A dropped file is streamed as the **raw request body** to a fresh, server-named
+file under the per-user work directory (default cap 2 GiB,
+`TEXTFLOWKIT_UI_MAX_UPLOAD_BYTES` overrides it); the size is capped both by the
+declared length and while streaming, and a refused, aborted, or oversized upload
+leaves no partial file. The staged path is generated by the server, never taken
+from the request, and a `mode: "upload"` submission names only an `upload_id`
+that is resolved back inside the uploads directory. Downloads come from a **fixed
+format allowlist** (TXT, Markdown, SRT, VTT, JSON, DOCX, PDF) rendered through the
+same `render` layer the other doors use; the filename is built from the job id,
+never from caller input.
+
+The UI adds **no new storage variable**: it fills in `TEXTFLOWKIT_DB`,
+`TEXTFLOWKIT_WORK_ROOT`, and `TEXTFLOWKIT_OUTPUT_ROOT` with per-user defaults
+(`%LOCALAPPDATA%\TextFlowKit\ui` on Windows) only when they are unset, so an
+explicit environment override is honoured unchanged.
+
 ## Durable job state
 
 By default jobs live in memory and are lost when the process exits. Set

{textflowkit-0.1.9 → textflowkit-0.1.10}/docs/architecture.md

@@ -7,18 +7,60 @@ current source paths noted throughout.
 
 ## One core, several doors
 
-TextFlowKit is a self-hosted media transcription library with a CLI and two
-adapters (MCP and a JSON HTTP API). Native Windows is the primary local target,
+TextFlowKit is a self-hosted media transcription library with a CLI, two adapters
+(MCP and a JSON HTTP API), and a local browser interface. Native Windows is the primary local target,
 including AMD ROCm through PyTorch for the explicit `whisper` engine; no WSL layer
 is involved. Linux and macOS are additional targets. The published website is
 static documentation and never runs the pipeline.
 
-![TextFlowKit shared-core architecture: four thin entry points (CLI, Python, MCP, HTTP) feed one core that acquires and decodes media, transcribes with the default Whistle engine or an explicitly selected openai-whisper, keeps job state and resume checkpoints in an optional SQLite store, adds optional speaker or translation postprocessing, and publishes TXT, SRT, VTT, JSON, Markdown, and optional DOCX/PDF exports.](assets/architecture-overview.svg)
+![TextFlowKit shared-core architecture: five thin entry points feed one core. The CLI, Python API, MCP, HTTP API, and the local browser UI (a fifth door that mounts the existing HTTP app under /api and shares the same job store, adding transport only, not a new pipeline) sit above one core that acquires and decodes media, transcribes with the default Whistle engine or an explicitly selected openai-whisper, keeps job state and resume checkpoints in an optional SQLite store, adds optional speaker or translation postprocessing, and publishes TXT, SRT, VTT, JSON, Markdown, and optional DOCX/PDF exports.](assets/architecture-overview.svg)
 
 As of v0.1.9 the default engine is **Whistle**, a CPU-only native CLI that needs
 no torch and downloads one pinned model on first use. `openai-whisper` is an
 explicit opt-in engine (`--engine whisper`), not the default.
 
+A **local browser interface** (`textflowkit-ui`) is a further door alongside the
+CLI, MCP, and HTTP entry points. It mounts the existing developer HTTP app under
+`/api` unchanged and adds only transport: a loopback-only browser session layer,
+a streamed upload, and a capability endpoint. It **ships in the core package as
+of v0.1.10** and adds no new dependency beyond the `http` extra. It is a local
+app: the published website is static documentation and never runs the pipeline.
+
+### One owner per database
+
+The durable SQLite store is owned by exactly one process. `textflowkit-ui`
+enforces that with an exclusive owner lock (`ui/ownership.py`) keyed by the
+**resolved** database path and taken *before* startup recovery runs. The lock is a
+genuine operating-system file lock (`msvcrt` on Windows, `flock` on POSIX) on a
+small sibling file that is created once and **never unlinked**, so there is no
+unlink/recreate window in which two processes could lock different inodes at one
+path. The kernel holds the lock for the live holder and releases it on exit *or
+crash*, so a run that was killed does not block the next launch. A second launch
+against a live owner does not start a competing server: it discovers the running
+instance's loopback URL from a small owner record written beside the lock and
+opens that instead. Ownership is proved by the held lock plus a matching owner
+record — never by signalling or inspecting a pid. A leftover URL record with no
+held lock is not treated as a live instance. Nothing here signals, stops, or
+cleans up any other process — the documented rule is simply **do not point two
+processes at one database file.**
+
+Readiness is a property of the process, not a probe: the launcher reserves the
+listening socket itself and drives uvicorn with `Server.serve(sockets=[...])`, so
+the browser is opened only after *our* server is serving, and an unrelated
+service holding the preferred port number is passed over for a genuinely free
+one.
+
+A **controlled shutdown** (`POST /ui/shutdown`, gated like every mutator by the
+loopback origin gate and the session capability header, and confirmed in the
+browser) asks this process's own uvicorn server to exit through its supported
+`should_exit` flag. The server then runs its normal lifespan teardown, which
+waits for the current jobs to finish before draining the worker pool rather than
+interrupting them, so a running job's saved progress survives and is resumable.
+It does not cancel an in-flight job; cancel it first for that. It never sends a
+signal to a pid. On a console
+(`pythonw`) launch the launcher keeps its own log file and reports a startup
+failure in a message box, so a shortcut that fails to start is not a silent exit.
+
 One shared submission contract (`core/submission.py`) owns job creation and
 resume for every door. The CLI runs the pipeline synchronously; MCP and HTTP
 enqueue work and return a job handle. The public Python `transcribe()` calls the
@@ -30,6 +72,7 @@ flowchart LR
     CLI[CLI single and batch] --> SUB[core.submission]
     MCP[MCP stdio or Streamable HTTP] --> SUB
     HTTP[JSON HTTP adapter] --> SUB
+    UI[Local browser UI over /api] --> SUB
     SUB --> STORE[Memory store or SQLite WAL]
     SUB --> EXEC[In-process bounded executor]
     SUB --> SYNC[Synchronous inline run]