# Changelog

English | [简体中文](CHANGELOG.zh-CN.md)

## 0.0.9 — 2026-10-28

### Changed

- Prepare the first public npm distribution under the unchanged package identity `fhgs-pi-rich-markdown`: remove the private barrier, declare public npm publication, and use an exact file allowlist with a package-local MIT license. Include runtime modules/workers, the synthetic demo asset and complete bilingual documentation; exclude tests, development/installer scripts, credentials, settings, conversation/history files, logs and dependency trees.
- Add npm tarball regressions for exact paths and bytes, synthetic privacy probes, extracted-package loading on both supported Pi hosts, local workers/preview assets and package-name/filter registration semantics. Keep all renderer behavior, commands, preferences, dependency pins and exact Pi 1.3.0/1.4.0 guards unchanged.
- Document pinned npm installation, deliberate upgrades, source-to-npm migration, rollback and removal without duplicate registrations. Retain the guided source installer as a separate alternative: npm excludes the lockfile it requires. Direct npm dependency versions remain pinned, but transitive resolution is not the source lockfile's reproducibility guarantee.
- Preserve the unpublished checkout-naming documentation change: the local checkout is `Orbit Tools`, while the GitHub repository remains `Orbit-Labs-AI/Orbit-Tools`. Keep the full 0.0.1–0.0.3 documented local history without inventing snapshots or tags.

### Fixed

- Validate the complete package-local MIT notice when testing standalone source snapshots, without requiring repository ancestors. Add an isolated regression that uses the same release-metadata checks directly and rejects missing or damaged notices without recursive test execution. Keep repository-license equality as a separate repository-only check.
- Keep native thumbnail/visual workers loadable from npm's `node_modules` directory, where Node refuses TypeScript stripping. Move the unchanged raster validator to plain ESM with a typed re-export and retain strict implementation type checking; its emitted JavaScript is identical after type erasure. Exercise all three native workers from an actual npm-style path, not only a source checkout. No rendering algorithm or resource limit changes.

### Verification

- Post-fix checks on macOS, Node.js 26.12.0 and official matching Pi SDK/TUI pairs: 687 tests on 1.3.0 and 691 on 1.4.0, zero failures/skips; both typechecks, locked installation and all 31 release-policy tests passed. Source and isolated installed-tarball production audits reported zero vulnerabilities. The real tarball passed worker/preview smoke tests and isolated Pi CLI install/repeat/list/remove checks on both hosts without live settings or installations.
- Release approval requires the commit-based validator on the committed 0.0.9 candidate against then-current `origin/main`, followed by validation of the release merge against its first parent before tagging/publication. These gates are separate from the local checks above; neither gate approval nor publication is claimed here.

### Upgrading

- Existing installations do not update automatically. Choose one npm or fresh-directory source procedure, retain the previous stable source for rollback, preserve resource filters and unrelated settings, and activate exactly one registration. Stop sessions using a managed npm copy before replacing it. Do not use bare `pi update`, which updates Pi itself.
- npm/tag installation commands require the version to have been published. Release preparation does not publish anything or change live installations. Physical-terminal graphics, IME and Linux execution remain unverified.

## 0.0.8 — 2026-10-23

### Changed

- Support Pi 1.4.0 for transcript rendering, rich input and local typing assistance while retaining exact Pi 1.3.0 compatibility. Keep private-API shape/ownership guards and native fallback for untested versions.
- Share an exact host-version allowlist between runtime adapters and host discovery. Require matching SDK/TUI versions, report the selected installer host accurately, and exercise the actual loaded version in tests and benchmarks rather than a hard-coded 1.3.0 label.
- Add Pi 1.4.0 CJK-emphasis and incomplete-math/table regressions, accepted-version and mixed-host checks, and bilingual compatibility guidance. The published 0.0.7 tag and existing installations are unchanged; install the 0.0.8 release into a fresh stable directory and replace only the existing package registration. No dependency versions or preferences change.

### Verification

- Release checks on macOS with Node.js 26.12.0: 688 tests on Pi 1.4.0 and 684 on Pi 1.3.0 passed with zero skips; both SDK type checks, locked installation, 31 release-policy tests and installer syntax checks passed. Runtime dependency audit: zero vulnerabilities. The integration test's release assertion and missing-Node guidance now match this release. Physical-terminal graphics, IME and Linux execution remain unverified; no paid model calls were used.

## 0.0.7 — 2026-10-19

The first GitHub 0.0.7 release follows published 0.0.6 and incorporates the earlier local 0.0.7 candidates. The dated local-candidate history below is not a second GitHub release.

### Added

- Render complete Mermaid fences with the full pinned Mermaid 12.2.0 engine (37 registered variants covered by local fixtures), including closed rich-input/dock fences. Fit both axes without truncating the drawing or reverting wide/tall diagrams to code. Show explicit unavailable notices for invalid, denied or resource-limited renders.
- Add fitted local raster images and `/rich-markdown view [demo]`; Ctrl+Alt+V selects visuals from the unsent draft. The isolated viewer rerasterizes original SVG/image data, with zoom, fit, original size and pan controls. Fullscreen supports buttons, Ctrl+wheel, Shift+wheel and drag; regular mode supports keyboard controls. Pi 1.3.0 does not expose native pinch gestures.
- Add a pinned puppeteer-core driver using installed Chrome/Chromium, a sandboxed private headless profile and DevTools pipe, strict protected configuration and blocked resource requests. No browser download, personal profile, model call or remote TUI image fetching. PNG/JPEG/GIF rendering needs no browser; static WebP uses Chrome.
- Add bounded queues/caches, latest-camera coalescing, browser launch/render deadlines, idle cleanup and independently verified child-process teardown. Close an open viewer before underlying graphics owners on reload/shutdown; keep its placements separate from input/dock/transcript. Resource bounds and terminal limitations are documented in both guides.
- Add live Markdown/LaTeX **inside the default input field**. Completed whole blocks render when the caret is outside their source or at the block end; entering a block reveals its full original source. A rendered-block click anchors to its source start, and vertical entry reveals the first/last source position. Plain text stays native. This is block-oriented live preview, not arbitrary formula-glyph-to-TeX caret mapping.
- Add `/rich-markdown input rich|source` and `/rich-markdown assist on|off`. Deterministic local assistance continues lists/tasks/quotes with the configured newline keys (Shift+Enter/Ctrl+J by default), exits empty markers, pairs delimiters with owned-closer type-through/empty-pair Backspace, and completes unambiguous math-only `frac`, `sqrt` and Greek-letter prefixes with Tab. Enter still submits; there is no snippet placeholder navigation, model call or semantic prose inference.
- Add an optional, separate read-only live draft dock, local image cards and compact path labels, including **Ctrl+Alt+I** exact-file consent for outside-cwd images. These features first appeared in the local candidates; this release makes the dock opt-in and shares image access with rich input.

### Changed

- Default to `input: "rich"`, `assist: true` and **`draft: false`**. Respect any explicitly saved `draft` boolean; missing `draft` now defaults to false. `/rich-markdown draft on|off` controls only the separate dock, not in-field rendering or assistance. `input source` retains native input without assistance; `assist off` retains rendering without typing changes.
- Keep the same native `CustomEditor` instance through guarded Pi 1.3.0 layout, hit-test and private-method wrappers, with no editor factory replacement. Preserve the paste registry/expansion, undo, history and application/extension shortcuts. Rendering never changes source submission; only explicit typing assistance edits source. Custom editors and native autocomplete retain native input; code/literal regions, command drafts, paste and IME batches are not assisted.
- Reuse bounded local images and exact-file consent for both input and dock. Input/dock cards use scroll-safe Kitty pixel placeholders on direct Ghostty/Kitty, with ANSI previews or explanatory labels elsewhere; static WebP requires the local browser decoder. Attachment metadata, uploads and model-attachment behavior are unchanged; a card is not proof of an attachment.

### Fixed

- Keep draft Markdown image tokens out of the transcript image loader, including references retained as source. Input/dock cards receive bytes only from the shared exact-file loader, preserving draft consent, selection and read limits instead of falling through to automatic transcript access.
- Isolate draft-derived Mermaid/raster requests and results in a cache shared by input and dock, separate from transcript visuals. Changing the selected image references, emptying/submitting the draft, disabling all draft views or image display, or disposing the draft service now clears that cache and its placements and retires its worker/browser; stale results cannot restore revoked data. Ordinary cursor/layout changes clear only affected placements, not cached data or consent. The explicit viewer remains independent.

### Safety and limits

- Bound input projection to 16,384 source characters, 128 blocks and 256 rendered rows per block, with source fallback. Keep the native input viewport limit of 30% terminal height with a minimum limit of five rows; the dock alone retains the 18-row/35% tail viewport and oversized-source paused notice.
- Render completed input LaTeX with separately owned Kitty placements or structural text/source fallback. Input, dock and transcript placements stay independent; input admits eight math image requests across all blocks per projection pass, while input/dock share a bounded transient math worker/cache separate from the transcript.
- Preserve exact-file identity/metadata checks, image read/size limits and stale-result rejection. Reference removal revokes its bytes/consent; clearing/submitting, disabling all draft views or image display, or unloading clears applicable access. `draft off` alone does not revoke images still used by rich input. No remote input-image fetching or preview uploads are added.
- Full visuals have a transcript cache, a separate shared input/dock cache and an independent cache per viewer. Queue, worker, result-cache and browser-layout budgets apply per cache, not once per session or per draft block; each surface retains independent terminal placements. See the guides for the numerical limits.

### Upgrading from 0.0.6 or a local 0.0.7 snapshot

- Use the release snapshot and a fresh `--dir` outside Git for both published 0.0.6 and earlier local 0.0.7 installations. A matching version string does not mean the new features or fixes are installed. Never overwrite an active source copy or repair its dependencies in place; replace only the existing Rich Markdown registration, retain the old copy for rollback and reload Pi. Follow the [upgrade guide](README.md#upgrading-from-006-or-a-local-007-snapshot); do not load two copies.
- Missing `input`/`assist` preferences select rich input and assistance; missing `draft` now means false, while an explicitly saved `draft: true` remains enabled. Use `input source`, `assist off` or `draft on` to choose the desired behavior without rewriting existing draft text.

### Notes

- Local post-fix verification on macOS with Pi SDK/TUI 1.3.0: **678 tests passed, zero failures/skips**, including installed-Chrome fixtures for all 37 registered Mermaid variants, real-SDK input/viewer lifecycle and draft-access/cache-revocation regressions. Locked dependency installation, TypeScript checking, 31 release-policy tests, installer shell/JavaScript syntax and whitespace checks passed; the runtime dependency audit reported zero vulnerabilities. Earlier measurements below apply only to their recorded local snapshots. Physical-terminal graphics, IME and Linux execution remain unverified; no paid model calls were used.
- Node.js 22.19+ and Pi SDK/TUI exactly 1.3.0 remain required. The full-visual path adds puppeteer-core and the documented installed-browser requirement for Mermaid/static WebP; it does not download Chrome/Chromium. No npm publication or active local installation change accompanies this release.

## 0.0.7 — local candidate history (2026-10-18)

These notes preserve the earlier local snapshot, including its then-current defaults, limitations and measured checks. They do not describe a separate GitHub release or tag and do not verify the final 2026-10-19 release above.

### Added

- Add an enabled-by-default, read-only live draft dock immediately **above** Pi's native editor, controlled by `draft: true` and `/rich-markdown draft on|off`. Formatted Markdown and completed LaTeX appear while typing; raw source remains editable below. This is not a full in-place WYSIWYG editor: no editor replacement/input hook, preserving native input and existing custom editors.
- Preview up to four local standalone paths or Markdown image references as compact basenames/cards, including quoted/escaped paths, `@`, `~/` and local file URLs. Use native image previews when protocol and `terminal.showImages` allow, with ANSI thumbnail/text fallback elsewhere; underlying path text is preserved.
- Compact eligible standalone image-path lines in Pi's default editor as filename labels. Move the cursor inside a path to reveal its source; the line end compacts it again. Keep native cursor markers, undo, paste expansion and submission, skip custom editors/autocomplete, and restore source rendering with `draft off`.
- Add **Ctrl+Alt+I** confirmation for exact canonical files outside the working directory, including Pi clipboard temporary paths. Authorization binds verified file metadata, never a folder. In-directory reads remain automatic when images are enabled; transcript thumbnail containment is unchanged.

### Safety and limits

- Keep draft rendering display-only: no uploads, remote fetching, network/UNC paths or input `data:` images, no prompt/submission changes or new session entries. An image card does not prove image bytes are attached to a model request; Pi inserts paths on clipboard image paste. Denied/unavailable images retain labels.
- Clear the dock on empty/submitted/off drafts, revoke exact-file consent and cached bytes when references are removed, and ignore stale reads/approvals. Limit drafts to 16,384 source characters with a paused notice above that limit, and a tail viewport capped at 18 rows / 35% terminal height. Limit images to four, 8 MiB each / 16 MiB total original bytes, four million pixels / 8,192 pixels per side, with serial five-second reads.
- Give draft formulas separate worker/cache and transport budgets from transcript graphics; draft changes do not invalidate transcript layout caches. Incomplete math and ordinary code remain literal; live Mermaid stays code instead of recomputing diagrams on every keystroke.
- Share raster-structure/frame-size validation between native previews and thumbnails; sanitize PNG metadata and GIF frames, cancel stale native consent dialogs, and constrain actual iTerm2 image geometry before drawing above the editor.

### Notes

- Update both user guides and the rendering design with draft commands/defaults, compact input labels, privacy, limits, cleanup and verification. Upgrade explicitly to a fresh 0.0.7 snapshot and reload Pi; keep the 0.0.6 copy for rollback. Node.js 22.19+ and Pi SDK/TUI exactly 1.3.0 remain required; no dependency versions change.
- Local verification on macOS: 517 tests passed with zero skips, TypeScript checking, runtime dependency audit with zero vulnerabilities, 31 release-policy tests, shell/JavaScript syntax checks, whitespace checks, 22 local documentation links/anchors and 10 shell examples. Physical Ghostty/Kitty graphics, IME, Linux execution and browser appearance remain manual validation items. This local version update does not publish a GitHub release or tag.

## 0.0.6 — 2026-10-18

### Added

- Add a guided `install.sh` / `npm run setup` workflow with read-only inspection, separate plugin/Ghostty consent, non-interactive flags, stable package copying, pinned runtime-dependency checks and a PNG smoke check before registration.
- Detect installed Ghostty/Kitty executables and macOS app bundles; skip an additional terminal when one is already available. Offer optional Ghostty through an existing Homebrew installation on local macOS, with official manual guidance elsewhere; do not bootstrap package managers or install competing Pi plugins.
- Add `/rich-markdown setup install` for existing users. Keep `/rich-markdown setup` read-only; no installer runs on extension load, during normal rendering, or in RPC/JSON/print mode.

### Changed

- Replace the dense `/rich-markdown status` notification with a read-only, theme-aware overlay: grouped overview, terminal capability, preferences and useful commands. The bare command opens the same screen; `d` switches to secondary diagnostics, keyboard navigation scrolls, and `Esc`/`Enter`/`Ctrl+C`/`q` closes it.
- Distinguish effective native/text/image rendering from potential terminal capability, including off/startup-failure and stopped-worker states. Keep unavailable counters and unmeasured latency distinct from zero; label Pi cell sizes as potentially default values.
- Support Unicode widths, resize, narrow/short terminals, configured Pi navigation keys and theme changes without extra fonts. Add real-SDK command and TUI overlay regressions; status remains read-only and independent of the explicitly approved installer.

### Fixed

- Refuse reused installation bundles with symlinked or special-file path components, including nested source directories, before dependency commands or settings changes. Preserve safe canonical destination-parent aliases.
- Revalidate cancellation targets against fresh process IDs, groups and start times before escalation and cleanup; discard missing/changed identities and never signal a closed launcher's cached group. Unverifiable descendants are left alone rather than trusting stale IDs; POSIX inspection/signalling remains best-effort, not atomic.

### Safety and verification

- Update bilingual release/install references and repair verification-guide links.
- Preserve existing source copies, unrelated settings, package resource filters and prior installations; update only one personal registration under Pi's settings lock and retain a private settings backup. Refuse duplicate registrations, concurrent replacement, active-copy dependency repair and Git checkout destinations.
- Bound installation commands, discard their output, disable Homebrew auto-update/analytics per process, and cancel subprocess groups on interruption or Pi reload/exit. Do not launch applications or force graphics settings; optional failures retain text/browser fallback.
- Add offline detector, consent, installer, registration and process-lifecycle regressions plus bilingual setup, privacy and removal guidance. Actual Homebrew/distro installation and physical graphics remain manual validation items.
- Exercise the status overlay, read-only setup, busy installer rejection and non-TUI isolation together so concurrent UI/setup changes cannot silently remove either command path.

## 0.0.5 — 2026-10-18

### Added

- Typeset inline and display LaTeX on Ghostty/Kitty using exact-cell transparent PNGs and scrollable Unicode placeholders, including real custom/Translator cards, quotes and lists.
- Render closed formulas during streaming; add the three classical-result examples to `demo math`. Add `setup`, `source`, `math text`, `images on|off`, `prompt on|off` and `clear-images` commands.
- Request LaTeX source with an optional, default-on TUI prompt guideline. Source-copy opens the original answer without sending it or saving edits.
- Document the graphics-terminal requirement, public Pi prior art, resource budgets and honest physical-terminal verification limits.

### Changed

- Cache uncolored SVG geometry separately from cell/theme-specific rasters; prewarm only supported image sessions and coalesce asynchronous repaint over 32 ms. Report last worker-job latency and provide a synthetic streaming benchmark.
- Preserve released portability and local-image security fixes, pinned dependencies, existing configuration/entry identities and non-TUI isolation. No Pi source or terminal configuration is patched.

### Fixed

- Handle same-size fullscreen clears and stop/start recovery; deduplicate uploads, bound pending transport data and avoid eviction of images still referenced by cached rows.
- Avoid Pi's SGR 58 ANSI-tracking incompatibility, split inline image fragments, unclosed-fence rasterization, unbounded pending/failed per-component admission and ignored inline `renderLatex: false`.
- Honor inline MathJax mode and bound the actual canvas rather than rejecting small formulas in large viewports. Isolate macros and unsupported tagged/glyph-dependent output.
- Wait for worker retirement before replacement, disable broken/continuously timing-out workers, discard worker diagnostics and bound request storage.
- Reuse native block-image components across defensive raster-cache copies, avoiding new image IDs on unchanged redraws. Respect the host's closing-fence indentation rules.
- Reject image-preference commands while busy/compacting, then reload after accepted changes so native image components and Rich Markdown agree.

### Notes

- Apple Terminal has no compatible graphics protocol; it retains text math and browser preview. tmux/screen also use text. Pixel formulas are not selectable text: use `source` for original LaTeX.
- Physical Ghostty/Kitty graphics, Linux execution and browser appearance remain manual validation items. Synthetic proofs are not live screenshots; measured local timings are not a universal latency guarantee.

## 0.0.4 — 2026-10-17

### Added

- Import the available Rich Markdown (richmd) 0.0.4 source into Orbit-Tools, including runtime code, synthetic demo assets and regression tests. Keep the original package name, commands and persisted entry identifiers.
- Provide English and Simplified Chinese installation, configuration, privacy, compatibility, verification and removal guides. Register the independent `rich-markdown` development branch and release policy.

### Changed

- Make test and typecheck host discovery independent of the author's installation layout. Require Pi SDK/TUI exactly 1.3.0; support `PI_SDK_PATH` and a standalone `PI_TRANSLATOR_CARD_PATH` override without silently skipping required regressions.
- Use the repository's Translator card for interoperability tests. Preserve the renderer implementation and pinned dependencies.

### Fixed

- Reject local image reads on unsupported platforms and reject network file paths before filesystem lookup. This prevents a rejected Windows `file:`/UNC reference from contacting an SMB share before containment checks. Add isolated no-filesystem-access regressions; the active local installation is not modified.
- Document the full suite's macOS/Linux requirement and the limits of simulated Windows, terminal and browser checks.

### Highlights

- Structural text equations and frameless display math, full-row colored surfaces, richer Markdown layouts, supported terminal Mermaid diagrams and bounded local raster thumbnails.
- Display-only recovery of short translated CJK bold labels, with code, escapes and stored source preserved.
- Explicit private browser previews with bundled rendering assets, per-preview remote-image consent and bounded image access.

### Notes

- This is the first repository source release, not a recreation of earlier releases. The local README documents 0.0.1–0.0.3, but separate snapshots and original release dates were not available. No historical tags or verification claims are invented.
- No npm publication, live installation changes, personal settings, session history or host release files are included. Pi compatibility remains exactly 1.3.0; physical terminal/browser appearance requires manual validation.

## 0.0.3 — documented local history

- Full-row colored backgrounds, terminal Mermaid and local raster thumbnails.
- Summary preserved from the imported local README; source snapshot, original date and independent verification are unavailable.

## 0.0.2 — documented local history

- Richer Markdown layouts and private browser previews.
- Summary preserved from the imported local README; source snapshot, original date and independent verification are unavailable.

## 0.0.1 — documented local history

- Initial local TUI rendering and MathJax formulas.
- Summary preserved from the imported local README; source snapshot, original date and independent verification are unavailable.