From 97b71416d5fb8ca9db1bac262288f307c256763a Mon Sep 17 00:00:00 2001 From: Ian Gulliver Date: Wed, 21 Oct 2026 12:40:06 -0700 Subject: [PATCH] Align documentation and wording with project conventions --- docs/macos.md | 4 ++-- docs/operations.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/macos.md b/docs/macos.md index 6f1fae4..3f5f2f9 100644 --- a/docs/macos.md +++ b/docs/macos.md @@ -34,7 +34,7 @@ Every build is signed for distribution outside the App Store: the team's Develop ## Views - The transcript is a plain `VStack` in a `ScrollView`, not lazy: a `LazyVStack` estimates the height of rows it hasn't shown yet and corrects it when they scroll into view, without moving the scroll offset, so scrolling up through rows not yet shown jumped by each correction; SwiftUI can't move the offset mid-scroll without stopping its momentum. -- The terminal cursor is a steady block: SwiftTerm's blinking cursor restarts its Core Animation fade on every keypress, scheduled 0.7 s out, and on a ProMotion display macOS then holds the window's screen update until that fade starts, so each typed letter appears about 0.7 s late. The terminal's colors are set once per light/dark scheme, since each color set makes SwiftTerm redraw the whole screen. +- The terminal cursor is a steady block: SwiftTerm's blinking cursor restarts its Core Animation fade on every keypress, scheduled 0.7 s out, and on a ProMotion display macOS then holds the window's screen update until that fade starts, so each typed letter appears about 0.7 s late. SwiftTerm redraws the whole screen whenever a terminal color is set, even when its value hasn't changed. ## Updates @@ -53,7 +53,7 @@ Places where SwiftUI alone may fall short, each checked side by side against its | Enter sends, Shift-Enter newline, nothing during IME composition | `TextEditor` with `onKeyPress` | `NSTextView` in an `NSViewRepresentable`, sending from `doCommand(by: insertNewline:)` | No fallback: `onKeyPress(.return)` runs before the `TextEditor`'s `NSTextView` and its input context. It sends, and returns `.ignored` for Shift so the text view adds the newline. Because it runs first, it must also return `.ignored` while the focused text view's `hasMarkedText()` is true, or Return sends the draft mid-composition. An in-process test that set marked text and delivered a Return `NSEvent` showed both: an unguarded handler sent the draft with the marked text still pending, and the guarded one passed Return on to the text view | | Image paste and drop into every box that talks to an agent | `onPasteCommand` and `onDrop` | The same `NSTextView`, overriding `paste(_:)` and drag handling | No fallback, but not through these two modifiers: `TextEditor`'s own text view takes ⌘V and drops before them and inserts the file's path as text. Instead the app replaces Edit's pasteboard group (`CommandGroup(replacing: .pasteboard)`): Paste attaches the clipboard's image when an image-taking box has focus and otherwise sends the ordinary `paste:`. Drops land on a `Color.clear` overlay on the `TextEditor` with `onDrop` and `allowsHitTesting(false)`: it still receives the drag, and clicks and typing pass through to the editor (with hit testing on, the editor can't be clicked) | | Transcript of a long task scrolling smoothly and staying stuck to the bottom | `VStack` in a `ScrollView` | `List` with its own row reuse | No fallback: the stack stays at the bottom while rows arrive and a message streams, and stays put when scrolled up. A `LazyVStack` jumped while scrolling up (see "Views") | -| Selecting text across blocks and messages | `textSelection(.enabled)` selects within one `Text` only | A selectable `NSTextView` in an `NSViewRepresentable` | Fallback used within a message: each run of consecutive paragraphs, headings and lists is one `NSAttributedString` in one non-editable text view, so a drag crosses blocks and bullets. Code blocks, diffs, tables, quotes, diagrams, `
`, paragraphs with images and choice lists stay SwiftUI views and end a run. Messages are still separate views, so each message is copied on its own | +| Selecting text across blocks and messages | `textSelection(.enabled)` selects within one `Text` only | A selectable `NSTextView` in an `NSViewRepresentable` | Fallback used within a message: a drag can cross consecutive paragraphs, headings and lists. Other block types and message boundaries still interrupt selection | | The terminal | No terminal view in SwiftUI | SwiftTerm's AppKit `TerminalView` in an `NSViewRepresentable` | Fallback used, as planned | | Font from `mac/fonts/` | Core Text | Convert the files to TTF in the build script | No fallback: Core Text reads the woff2 files and their `wght` axis (200–800) | | SVG images from the worktree image endpoint | `NSImage(data:)` | Show the "image not available" text | No fallback: `NSImage(data:)` decodes SVG and draws it sharp at any size | diff --git a/docs/operations.md b/docs/operations.md index 00bc751..2fd428a 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -6,7 +6,7 @@ What reading byre's code won't tell you: external setup, vendor and platform qui State lives in the directory given by `byre serve --data`, by default `~/Library/Application Support/byre`: `byre.db` (SQLite, WAL), task worktrees under `worktrees/`, uploaded images under `blobs/`. This directory is private to the service's OS user (0700), including on existing installations: it contains transcripts, credentials and local agent listener bearer URLs. Other processes running as that same OS user remain trusted. -Migrations are the files in `internal/store/migrations/` (`NNN-name.sql`), plus Go data migrations in `goMigrations`. The number only orders; a migration is identified by its name. A migration's SQL is fixed once applied anywhere: write it out in full rather than sharing Go constants that later change. Concurrent task branches can each add migrations, so after a merge a migration can land before others the database has already applied, and it still runs. Give a new migration a name no other branch will use, and make any data migration safe to run twice. `sqlite3 byre.db 'SELECT * FROM migrations'` lists what has been applied. +Add SQL migrations in `internal/store/migrations/` as `NNN-name.sql`. The number only orders; a migration is identified by its name. A migration's SQL is fixed once applied anywhere: write it out in full rather than sharing Go constants that later change. Concurrent task branches can each add migrations, so after a merge a migration can land before others the database has already applied, and it still runs. Give a new migration a name no other branch will use, and make any data migration safe to run twice. `sqlite3 byre.db 'SELECT * FROM migrations'` lists what has been applied. ## Worktrees