diff --git a/README.md b/README.md index 5460a1f7d..d6c65de1d 100644 --- a/README.md +++ b/README.md @@ -324,21 +324,20 @@ Benchmarked across 16 models, 180 tasks, 3 runs each: ~7,500 lines of Rust compiled to a platform-tagged N-API addon, providing performance-critical operations without shelling out to external commands: -| Module | Lines | What it does | Powered by | -| --------------- | -----: | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -| **grep** | ~1,300 | Regex search over files and in-memory content, parallel/sequential modes, glob/type filtering, context lines, fuzzy find for autocomplete | `grep-regex`, `grep-searcher`, `grep-matcher` (ripgrep internals) | -| **shell** | ~1,025 | Embedded bash execution with persistent sessions, streaming output, timeout/abort, custom builtins | [brush-shell](https://github.com/reubeno/brush) (vendored) | -| **text** | ~1,280 | ANSI-aware visible width, truncation with ellipsis, column slicing, text wrapping that preserves SGR codes across line breaks — all UTF-16 optimized | `unicode-width`, `unicode-segmentation` | -| **keys** | ~1,300 | Kitty keyboard protocol parser with legacy xterm/VT100 fallback, modifier support, PHF perfect-hash lookup | `phf` | -| **highlight** | ~475 | Syntax highlighting with 11 semantic color categories, 30+ language aliases | `syntect` | -| **glob** | ~340 | Filesystem discovery with glob patterns, type filtering, mtime sorting, `.gitignore` respect | `ignore`, `globset` (ripgrep internals) | -| **task** | ~350 | Blocking work scheduler on libuv thread pool, cooperative/external cancellation, timeout, profiling hooks | `tokio`, `napi` | -| **ps** | ~290 | Cross-platform process tree kill and descendant listing — `/proc` on Linux, `libproc` on macOS, `CreateToolhelp32Snapshot` on Windows | `libc` | -| **prof** | ~250 | Always-on circular buffer profiler with folded-stack output and optional SVG flamegraph generation | `inferno` | -| **system_info** | ~170 | Distro, kernel, CPU, disk usage without shelling out | `sysinfo` | -| **image** | ~150 | Decode/encode PNG/JPEG/WebP/GIF, resize with 5 sampling filters | `image` | -| **clipboard** | ~95 | Text copy and image read from system clipboard — no `xclip`/`pbcopy` needed | `arboard` | -| **html** | ~50 | HTML-to-Markdown conversion with optional content cleaning | `html-to-markdown-rs` | +| Module | Lines | What it does | Powered by | +| ------------- | -----: | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | +| **grep** | ~1,300 | Regex search over files and in-memory content, parallel/sequential modes, glob/type filtering, context lines, fuzzy find for autocomplete | `grep-regex`, `grep-searcher`, `grep-matcher` (ripgrep internals) | +| **shell** | ~1,025 | Embedded bash execution with persistent sessions, streaming output, timeout/abort, custom builtins | [brush-shell](https://github.com/reubeno/brush) (vendored) | +| **text** | ~1,280 | ANSI-aware visible width, truncation with ellipsis, column slicing, text wrapping that preserves SGR codes across line breaks — all UTF-16 optimized | `unicode-width`, `unicode-segmentation` | +| **keys** | ~1,300 | Kitty keyboard protocol parser with legacy xterm/VT100 fallback, modifier support, PHF perfect-hash lookup | `phf` | +| **highlight** | ~475 | Syntax highlighting with 11 semantic color categories, 30+ language aliases | `syntect` | +| **glob** | ~340 | Filesystem discovery with glob patterns, type filtering, mtime sorting, `.gitignore` respect | `ignore`, `globset` (ripgrep internals) | +| **task** | ~350 | Blocking work scheduler on libuv thread pool, cooperative/external cancellation, timeout, profiling hooks | `tokio`, `napi` | +| **ps** | ~290 | Cross-platform process tree kill and descendant listing — `/proc` on Linux, `libproc` on macOS, `CreateToolhelp32Snapshot` on Windows | `libc` | +| **prof** | ~250 | Always-on circular buffer profiler with folded-stack output and optional SVG flamegraph generation | `inferno` | +| **image** | ~150 | Decode/encode PNG/JPEG/WebP/GIF, resize with 5 sampling filters | `image` | +| **clipboard** | ~95 | Text copy and image read from system clipboard — no `xclip`/`pbcopy` needed | `arboard` | +| **html** | ~50 | HTML-to-Markdown conversion with optional content cleaning | `html-to-markdown-rs` | Supported platforms: `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`, `win32-x64`. diff --git a/docs/natives-media-system-utils.md b/docs/natives-media-system-utils.md index 5538e0554..0e78a0347 100644 --- a/docs/natives-media-system-utils.md +++ b/docs/natives-media-system-utils.md @@ -1,13 +1,12 @@ # Natives media + system utilities -This document is a subsystem deep-dive for the **system/media/conversion primitives** layer described in [`docs/natives-architecture.md`](./natives-architecture.md): `image`, `html`, `clipboard`, `system-info`, and `work` profiling. +This document is a subsystem deep-dive for the **system/media/conversion primitives** layer described in [`docs/natives-architecture.md`](./natives-architecture.md): `image`, `html`, `clipboard`, and `work` profiling. ## Implementation files - `crates/pi-natives/src/image.rs` - `crates/pi-natives/src/html.rs` - `crates/pi-natives/src/clipboard.rs` -- `crates/pi-natives/src/system_info.rs` - `crates/pi-natives/src/prof.rs` - `crates/pi-natives/src/task.rs` - `packages/natives/src/image/index.ts` @@ -16,8 +15,6 @@ This document is a subsystem deep-dive for the **system/media/conversion primiti - `packages/natives/src/html/types.ts` - `packages/natives/src/clipboard/index.ts` - `packages/natives/src/clipboard/types.ts` -- `packages/natives/src/system-info/index.ts` -- `packages/natives/src/system-info/types.ts` - `packages/natives/src/work/index.ts` - `packages/natives/src/work/types.ts` @@ -25,16 +22,15 @@ This document is a subsystem deep-dive for the **system/media/conversion primiti ## TS API ↔ Rust export/module mapping -| TS export (packages/natives) | Rust N-API export | Rust module | -| --- | --- | --- | -| `PhotonImage.parse(bytes)` | `PhotonImage::parse` (`js_name = "parse"`) | `image.rs` | -| `PhotonImage#resize(width, height, filter)` | `PhotonImage::resize` (`js_name = "resize"`) | `image.rs` | -| `PhotonImage#encode(format, quality)` | `PhotonImage::encode` (`js_name = "encode"`) | `image.rs` | -| `htmlToMarkdown(html, options)` | `html_to_markdown` (`js_name = "htmlToMarkdown"`) | `html.rs` | -| `copyToClipboard(text)` | `copy_to_clipboard` (`js_name = "copyToClipboard"`) + TS fallback logic | `clipboard.rs` + `clipboard/index.ts` | -| `readImageFromClipboard()` | `read_image_from_clipboard` (`js_name = "readImageFromClipboard"`) | `clipboard.rs` | -| `getSystemInfo()` | `get_system_info` (`js_name = "getSystemInfo"`) | `system_info.rs` | -| `getWorkProfile(lastSeconds)` | `get_work_profile` | `prof.rs` | +| TS export (packages/natives) | Rust N-API export | Rust module | +| ------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------- | +| `PhotonImage.parse(bytes)` | `PhotonImage::parse` (`js_name = "parse"`) | `image.rs` | +| `PhotonImage#resize(width, height, filter)` | `PhotonImage::resize` (`js_name = "resize"`) | `image.rs` | +| `PhotonImage#encode(format, quality)` | `PhotonImage::encode` (`js_name = "encode"`) | `image.rs` | +| `htmlToMarkdown(html, options)` | `html_to_markdown` (`js_name = "htmlToMarkdown"`) | `html.rs` | +| `copyToClipboard(text)` | `copy_to_clipboard` (`js_name = "copyToClipboard"`) + TS fallback logic | `clipboard.rs` + `clipboard/index.ts` | +| `readImageFromClipboard()` | `read_image_from_clipboard` (`js_name = "readImageFromClipboard"`) | `clipboard.rs` | +| `getWorkProfile(lastSeconds)` | `get_work_profile` | `prof.rs` | ## Data format boundaries and conversions @@ -81,15 +77,6 @@ Conversion behavior: - Rust re-encodes it to PNG bytes (`image` crate), returns `{ data: Uint8Array, mimeType: "image/png" }`. - TS returns `null` early on Termux or Linux sessions without display server (`DISPLAY`/`WAYLAND_DISPLAY` missing). -### System info (`system-info`) - -- **Output boundary**: plain object returned synchronously. -- Rust currently populates: `distro`, `kernel`, `cpu`, `disk`. -- Linux distro comes from `/etc/os-release` parsing; macOS may append a marketing name (`Tahoe`, `Sequoia`, etc.) to OS version text. -- Disk summary is normalized to human-readable strings (`used/total (pct%)`), with platform-dependent selection: - - Windows: aggregates each mount entry. - - non-Windows: prefers `/`, falls back to first disk. - ### Work profiling (`work`) - **Collection boundary**: profiling samples are produced by `profile_region(tag)` guards in `task::blocking` and `task::future`. @@ -141,18 +128,6 @@ Failure transitions: 3. `ContentNotAvailable` maps to `null`. 4. Other Rust errors reject. -### System info lifecycle - -1. `getSystemInfo()` refreshes `sysinfo::System` and disk list synchronously. -2. Per-platform helpers derive distro/kernel/cpu/disk snapshots. -3. Object is returned directly; no async task scheduling. - -Failure transitions: - -- Missing optional data degrades to omitted fields (`Option::None`), not thrown errors. -- `/etc/os-release` parse failures are soft-fail (`None` distro). -- Disk total space `0` is treated as unavailable (`None` disk). - ### Work profiling lifecycle 1. No explicit start: profiling is always on when task helpers execute. @@ -184,11 +159,6 @@ Failure transitions: - Image read distinguishes "no image" (`null`) from operational failure (rejection). - Termux/headless Linux are treated as unsupported contexts for image read (`null`). -### System info - -- Designed for partial success: fields are optional and may be absent by platform. -- Current TS type is broader than current Rust-populated fields; maintainers should expect sparse payloads unless Rust expands output. - ### Work profiling - Retrieval is strict for function call itself, but artifact generation is partially best-effort (`svg` nullable). @@ -198,5 +168,3 @@ Failure transitions: - **Clipboard text**: OSC 52 depends on terminal support; native clipboard access depends on desktop environment/session. - **Clipboard image read**: blocked in TS for Termux and Linux without display server. -- **System info distro**: Linux distro name quality depends on `/etc/os-release` fields; macOS marketing name mapping is version-table-based and may lag new releases. -- **Disk reporting**: Windows returns a comma-separated multi-volume summary; non-Windows returns one primary mount summary.