release: prepare Shift 0.1.9

Version, the release docs and the engineering ledger for the two installers.

The ledger gains a section on the Runtime components panel, because the bug it
records was invisible rather than broken: a dropped `return` made macOS answer
the document-PDF row with a Pandoc pipeline it never uses, so the panel reported
a missing component with no way to install it. The section states the invariant
that a row may not read as missing unless it also offers a way forward, which is
the part a future refactor is most likely to lose again.

README sections that described dropping files as "opens the action ring" now
describe the aimed rule, and the capture-behaviour option is gone from the
Settings tour.
main
mula.liu 2026-11-01 12:04:03 +08:00
parent e6818e029e
commit b524b69fc8
9 changed files with 126 additions and 34 deletions

View File

@ -40,13 +40,13 @@ Built on Tauri 2, Rust, React and TypeScript. Native capture and drag behaviour
## What it does
**The radial menu is the whole interface.** Hold `Shift` and drag a file in Finder (or `Shift + Alt` on Windows) and a ring opens under the cursor. Release over a format to convert, or add `Option`/`Alt` to switch to the tool ring. The main window accepts drops too, and its `Convert files` / `File tools` buttons open the same rings for files you pick yourself.
**The radial menu is the whole interface.** Hold `Shift` and drag a file in Finder (or `Shift + Alt` on Windows) and a ring opens under the cursor. Release over a format to convert, or add `Option`/`Alt` to switch to the tool ring. In the main window the same rings open from a file you drop on one of the three buttons, or pick through `Convert files` / `File tools`.
**Everything is type-aware.** The ring only offers what the selected file can actually become, and never repeats the source format — an image can target PNG/JPG/WEBP/HEIC/TIFF/BMP/GIF/PDF except its current format, a PPTX offers PDF and Markdown, and a `.key` or `.pages` file offers no conversion wedges at all instead of failing later. The centre shows a glass preview with the file's dimensions and size; a multi-file selection renders a stacked icon deck.
**Batch by default.** Select ten files, drag, and one gesture produces ten outputs. Results land next to each source with a descriptive suffix (`report (compressed).pdf`, `photo (rotated).png`) and never overwrite — a numeric suffix is appended on collision. Settings can collect every result into one folder instead.
**Capture is built in.** Frozen-screen area capture, full-screen capture, and area recording with a floating timer, all aimed at the monitor under the pointer rather than always the primary display. A finished capture hands you a floating result card - Copy, Pin, Send, Reveal, Edit, one click each, and it steps aside on its own - or opens the annotation canvas straight away, whichever you choose in Settings. Recording options only ever offer what your platform actually does: microphone on macOS, frame rate on the FFmpeg backends.
**Capture is built in.** Frozen-screen area capture, full-screen capture, and area recording with a floating timer, all aimed at the monitor under the pointer rather than always the primary display. A finished capture hands you a floating result card - Copy, Pin, Send, Reveal, Edit, one click each, and it steps aside on its own. Recording options only ever offer what your platform actually does: microphone on macOS, frame rate on the FFmpeg backends.
**The rings are yours to arrange.** A saved order rearranges the wedges for each file type and each ring, so the convert you use hourly sits at the top of an image's action ring rather than the bottom. (The Settings screen that edited those orders was removed, so orders are applied from `settings.json` rather than changed in the app.)
@ -72,7 +72,7 @@ Shift lives in the menu bar (macOS) and the notification area (Windows), and it
**Use a tool (`Option + Shift`, or `Alt + Shift` on Windows).** Same gesture, and the wedges become tools for that file type instead of formats. While the ring is open, keep `Shift` held and press or release `Option`/`Alt` to flip between the format ring and the tool ring.
**Prefer not to drag?** In the main window, **Convert files** and **File tools** open a picker and then show the same ring for what you chose; **OCR** picks an image and reads it. Dropping files straight onto the main window opens the action ring directly. Drop them **onto a button** instead and that button lights up and runs its own action: **Convert files** opens the format ring, **File tools** the tool ring, **OCR** reads the image.
**Prefer not to drag?** In the main window, **Convert files** and **File tools** open a picker and then show the same ring for what you chose; **OCR** picks an image and reads it. Dropping a file is **aimed**: the three buttons are the only drop targets, and the button you release on is the action it runs - **Convert files** opens the format ring, **File tools** the tool ring, **OCR** reads the image. All three light up as candidates while a drag is in flight; release anywhere else on the panel and nothing runs, with a note that the drop needs a button.
**Several files at once.** Multi-select with `⌘`/`Ctrl`-click, then drag. Every file is processed. With 2+ images or 2+ PDFs selected, a **Merge** wedge appears that combines them into a single PDF.
@ -191,7 +191,7 @@ PDF→image and PDF split write into a new `Name pages` folder containing `Page
**Recording options are honest.** `capabilities()` in `src-tauri/src/recording.rs` reports what the backend actually implements, and the capture toolbar renders only those switches. macOS gets the microphone toggle (`screencapture -g`) and no frame-rate control, because `screencapture -v` has none; Windows and Linux get a frame-rate chip (15 / 24 / 30) that becomes ffmpeg's `-framerate`, and no microphone toggle, because no audio input is wired into the grab yet. Nothing in the UI can promise a setting the encoder would silently drop.
**Result card.** A finished screenshot or recording appears bottom-right as a card with **Copy**, **Pin**, **Send**, **Reveal** and **Edit**. Hovering holds it open; otherwise it steps aside on its own. Settings -> Screenshots chooses what happens at that moment - **Result card** or **Open in editor** - and the editor is the fallback whenever a card window cannot be created.
**Result card.** A finished screenshot or recording appears bottom-right as a card with **Copy**, **Pin**, **Send**, **Reveal** and **Edit**. Hovering holds it open; otherwise it steps aside on its own. The editor is the fallback whenever a card window cannot be created, so a capture is never left with no way to act on it.
**Annotation.** The editor canvas works at native resolution and writes a new PNG, so the source file is never modified.
@ -220,6 +220,7 @@ Every capture, conversion result and received file is written by Rust into one l
- **Favorite** a row to keep it through the capacity limit, a deleted file, and Clear.
- **Remove** one row, or **Clear** the library - favorite rows stay.
- **Drag a row out** into Finder, a mail composer or a chat window: the row carries a `file://` URL, so the receiving application gets the file rather than a path string. The plain-text path travels with it for editors.
- **Drag a row onto Convert files, File tools or OCR** to run just that action on a file you already used — the same gesture, inverted. Like any drop it has to land on a button; releasing it back over the list runs nothing.
- Click a row to open it in the editor; the row's other buttons send, reveal, and pin it to the screen.
## OCR
@ -292,7 +293,7 @@ Each is overridable in Settings. File actions offer a *collect everything in one
## Updates
A new macOS machine installs **`Shift-0.1.8-macOS-universal.dmg`**: builds are ad-hoc signed and not notarized, so Gatekeeper calls Shift an unidentified developer. Double-click the image, drag `Shift.app` to /Applications, then allow the first launch once (right-click → Open, or 允许 in System Settings → Privacy & Security). In-app updates download the same image without a browser, so they never prompt. Details in `docs/RELEASE.md`.
A new macOS machine installs **`Shift-0.1.9-macOS-universal.dmg`**: builds are ad-hoc signed and not notarized, so Gatekeeper calls Shift an unidentified developer. Double-click the image, drag `Shift.app` to /Applications, then allow the first launch once (right-click → Open, or 允许 in System Settings → Privacy & Security). In-app updates download the same image without a browser, so they never prompt. Details in `docs/RELEASE.md`.
The update channel is this repository: a `releases` branch holding the installers plus `shift-update.json`, which names each artifact, its size and its SHA256. The feed URL is derived from the git remote at build time - Gitea, GitHub and GitLab forms are known, and `SHIFT_UPDATE_URL` overrides it - so no update service has to be deployed anywhere.
@ -315,9 +316,11 @@ Core conversion, radial menu, capture, and OCR work with nothing installed. Thes
| LAME | MP3 encode when FFmpeg lacks `libmp3lame` | rare | rare | rare |
Settings -> **Runtime components** shows the tools found on the current machine,
their versions and paths. Missing Pandoc, Typst, FFmpeg, Poppler and ImageMagick can be
installed from the same panel through Homebrew on macOS or WinGet on Windows,
then detected again automatically. Tools are also found on `PATH` and their
their versions and paths, and what each one unlocks on this platform. A row that reads
as missing also says how to fix it: anything installable carries an **Install** button
(Pandoc and FFmpeg on macOS through Homebrew; Pandoc, FFmpeg, Poppler, ImageMagick and
Typst on Windows through WinGet), and a row with no button is either built in or simply
not used on that platform. Tools are also found on `PATH` and their
standard install locations at call time, so a missing dependency degrades one
wedge rather than the app.
@ -331,7 +334,7 @@ wedge rather than the app.
| Monitor under cursor | Yes | Yes | `grim` output selection |
| Area recording | `screencapture -v`, audio via `-g` | FFmpeg `x11grab` | `wf-recorder` under Wayland, FFmpeg `x11grab` under X11 |
| Recording frame-rate control | not offered (`screencapture` has none) | 15 / 24 / 30 | 15 / 24 / 30 (`-r` / `-framerate`) |
| History library, drag a row out | Yes | Yes | Yes |
| History library, drag a row out and back onto a button | Yes | Yes | Yes |
| Git-backed updates: SHA256 gate, optional signed manifest | Yes | x64 is the published installer; an ARM machine gets it through the `windows` fallback | Checks and downloads; nothing published for Linux, so the answer is "no artifact" |
| Image convert and edit | Yes | Yes | Yes |
| HEIC / AVIF encode | `sips` | ImageMagick | ImageMagick |
@ -371,7 +374,7 @@ pnpm mac:release
scripts/build-windows-release.sh
```
The release pipeline deliberately emits exactly two installers: `Shift-0.1.8-macOS-universal.dmg` and `Shift-Setup-0.1.8-win-x64.exe`. The macOS app is one universal Mach-O including universal drag, PDF-render and doc-render sidecars. Windows ARM64 uses the x64 installer through the update manifest's compatibility fallback. Full details are in `docs/BUILD_WINDOWS.md` and `docs/RELEASE.md`.
The release pipeline deliberately emits exactly two installers: `Shift-0.1.9-macOS-universal.dmg` and `Shift-Setup-0.1.9-win-x64.exe`. The macOS app is one universal Mach-O including universal drag, PDF-render and doc-render sidecars. Windows ARM64 uses the x64 installer through the update manifest's compatibility fallback. Full details are in `docs/BUILD_WINDOWS.md` and `docs/RELEASE.md`.
**Permissions (macOS).** Screen Recording for capture, Files & Folders for the output folders you choose, Microphone when recording with audio, and Local Network for **Send to a device**. Shift checks Screen Recording before opening the overlay, so a denial surfaces an actionable error rather than a black screenshot. A denied Local Network grant is quieter: Shift still sends its beacons and still answers anyone who addresses it directly, but it receives no group traffic, so the device list simply stays empty. Ad-hoc signed builds get a new code identity on every rebuild and macOS keys these grants to that identity, so an upgrade can ask again; distribution with Developer ID keeps them stable.
@ -451,7 +454,7 @@ The one exception is opt-in by usage: **Send to a device** talks to your local n
- PDF compression resamples embedded images to at most 1440 px as q60 JPEG. It deliberately skips anything it cannot prove it can round-trip — masks, indexed or CMYK colour, JPX/JBIG2/CCITT — so exotic scans may still resist shrinking.
- Windows recording and media conversion require `ffmpeg` on `PATH`. On Linux media conversion also requires it, area recording needs `wf-recorder` under Wayland and `ffmpeg` under X11, and neither path is exercised by the forge this repository is hosted on, so treat Linux capture as build-verified only.
- Linux is a build target, not a shipped product: no deb or AppImage is published, so the update channel carries no `linux` key and a Linux build finds nothing to download. `scripts/linux/Dockerfile` and the `linux` job in CI remain the recipe for anyone who wants one.
- Dragging a library row out uses the webview's file-URL drag support. It is the standard `text/uri-list` payload with a `file://` entry plus the plain path, and it needs a gesture-level check on each platform; until then, **Send**, **Reveal** and the row's own buttons are the guaranteed paths for handing a file over.
- Dragging a library row out uses the webview's file-URL drag support. It is the standard `text/uri-list` payload with a `file://` entry plus the plain path, and it needs a gesture-level check on each platform; until then, **Send**, **Reveal** and the row's own buttons are the guaranteed paths for handing a file over. Dropping a row back onto Shift is checked: one gesture reports through the DOM, the native webview drop, or both, and the `landed` flag in `MainWindow.tsx` lets only the first through — the invariants are in `docs/ENGINEERING-NOTES.md`.
- LAN sharing needs a network that allows peer traffic. Multicast is skipped by some guest and corporate Wi-Fi; those networks still work over the broadcast and unicast fallbacks, but two copies cannot meet across a router that isolates clients. The discovery invariants, permission checks and regression matrix are in `docs/ENGINEERING-NOTES.md`.
- On Windows only one Shift copy per machine can hold the discovery port, so extra instances do not appear as peers.
- Windows and Linux paths are compile-verified here, and the forge hosting this repository runs no Actions, so nothing is ever built by CI on your behalf. Gesture-level QA needs real Windows and Linux hardware.

View File

@ -40,13 +40,13 @@ Shift 把文件格式转换、截图、录屏、标注、中英双语 OCR 全部
## 能力概览
**环形菜单就是全部交互。** 在访达中按住 `Shift` 拖动文件(Windows 为 `Shift + Alt`),圆环会出现在光标下方。松开在某个格式上即完成转换;再加上 `Option`/`Alt` 可切换到工具环。主窗口同样接受拖放,其「文件转换」与「文件工具」按钮会先让你挑选文件,再弹出同一个圆环。
**环形菜单就是全部交互。** 在访达中按住 `Shift` 拖动文件(Windows 为 `Shift + Alt`),圆环会出现在光标下方。松开在某个格式上即完成转换;再加上 `Option`/`Alt` 可切换到工具环。在主窗口里,把文件拖到三个按钮之一也会弹出同一个圆环,或者用「文件转换」「文件工具」先挑文件再弹环。
**一切按类型驱动。** 圆环只列出所选文件真正能变成的格式,并且不会重复显示文件自身的格式——图片可在 PNG/JPG/WEBP/HEIC/TIFF/BMP/GIF/PDF 之间转换,但当前格式不会出现目标;PPTX 给出 PDF 与 Markdown,而 `.key`、`.pages` 文件不会给出任何转换扇区,而不是等你点击后才失败。中心是毛玻璃预览,显示尺寸与体积;多选文件会渲染成一叠层叠图标。
**默认批量处理。** 选中十个文件、一次拖拽,就产出十个结果。结果保存在源文件旁边并附带描述性后缀(`report (compressed).pdf`、`photo (rotated).png`),永不覆盖——重名时自动追加序号。也可在设置中改为统一收集到一个文件夹。
**截图能力内置。** 冻结画面的区域截图、全屏截图,以及带悬浮计时器的区域录屏;一律对准光标所在的显示器,而非固定主屏。一次截图完成后会弹出一张浮动结果卡片——复制、钉住、发送、在文件夹中显示、编辑,各一键完成,稍候自行退场;也可在设置里改成直接进入标注画布。截图与录屏选项只给出当前平台真正支持的开关:macOS 提供麦克风,FFmpeg 后端提供帧率。
**截图能力内置。** 冻结画面的区域截图、全屏截图,以及带悬浮计时器的区域录屏;一律对准光标所在的显示器,而非固定主屏。一次截图完成后会弹出一张浮动结果卡片——复制、钉住、发送、在文件夹中显示、编辑,各一键完成,稍候自行退场。截图与录屏选项只给出当前平台真正支持的开关:macOS 提供麦克风,FFmpeg 后端提供帧率。
**圆环顺序由你决定。** 已保存的顺序会按文件类型、按环重新排列扇区,最常用的转换不再压在扇区环的最下面。(调整顺序的设置标签页已移除,顺序改由 `settings.json` 提供,应用内暂无修改入口。)
@ -72,7 +72,7 @@ Shift 常驻菜单栏(macOS)与通知区域(Windows),同时也有普
**使用工具(`Option + Shift`,Windows 为 `Alt + Shift`)** 操作相同,扇区会从格式换成该类型文件可用的工具。圆环打开时,保持按住 `Shift`,再按下或松开 `Option`/`Alt`,即可在格式环与工具环之间来回切换。
**不想拖动?** 主窗口中的「文件转换」与「文件工具」会先让你挑选文件,然后对选中的文件弹出同一个圆环;「文字识别」则选取图片并识别。直接把文件拖到主窗口上,会直接打开操作环。**拖到按钮上**则按钮会高亮并只执行它自己的操作:「文件转换」打开格式环,「文件工具」打开工具环,「文字识别」直接识别图片。
**不想拖动?** 主窗口中的「文件转换」与「文件工具」会先让你挑选文件,然后对选中的文件弹出同一个圆环;「文字识别」则选取图片并识别。拖放文件必须**对准按钮**:三个按钮是唯一的落点,松开在哪个按钮上就执行那个按钮的动作——「文件转换」打开格式环,「文件工具」打开工具环,「文字识别」直接识别图片。拖拽进行中三个按钮会同时显示为候选落点;松开在面板其他位置不会执行任何操作,并提示需要拖到按钮上。右侧「最近使用」里的条目同样可以拖到这三个按钮上,用同一次拖拽复用已经处理过的文件。
**一次处理多个文件。** 用 `⌘`/`Ctrl` 点选多个文件后一起拖动,每个文件都会被处理。选中 2 张以上图片或 2 个以上 PDF 时,会出现「合并」扇区,把它们合成一个 PDF。
@ -191,7 +191,7 @@ PDF 转图片与 PDF 拆分会新建 `名称 pages` 文件夹,内含 `Page 001
**录屏选项是诚实的。** `src-tauri/src/recording.rs` 中的 `capabilities()` 报告当前后端真正实现的能力,截图工具条只渲染这些开关。macOS 有麦克风开关(`screencapture -g`)而没有帧率选项,因为 `screencapture -v` 根本不支持帧率;Windows 与 Linux 提供 15 / 24 / 30 三档帧率,它会成为 ffmpeg 的 `-framerate`,但没有麦克风开关,因为抓屏尚未接入音频输入。界面上不存在“按了却被编码器默默忽略”的选项。
**结果卡片。** 截图或录屏完成后,右下角出现一张卡片,提供**复制**、**钉住**、**发送**、**在文件夹中显示**、**编辑**。鼠标悬停时卡片停留,否则自行退场。设置 → 截图 可选择这一刻的行为是**结果卡片**还是**在编辑器中打开**;当卡片窗口无法创建时会自动回退到编辑器。
**结果卡片。** 截图或录屏完成后,右下角出现一张卡片,提供**复制**、**钉住**、**发送**、**在文件夹中显示**、**编辑**。鼠标悬停时卡片停留,否则自行退场。当卡片窗口无法创建时会自动回退到编辑器,因此一次截图不会落不到任何后续操作上。
**标注。** 编辑器画布按原始分辨率工作,并写出新的 PNG,因此源文件永远不会被修改。
@ -220,6 +220,7 @@ PDF 转图片与 PDF 拆分会新建 `名称 pages` 文件夹,内含 `Page 001
- **收藏**某一行,即可在容量上限、文件被删除、以及「清空」之后仍然保留。
- **移除**单行,或**清空**整个库——收藏项会保留。
- **把某一行拖出去**即可交给访达、邮件撰写窗口或聊天软件:该行携带 `file://` 链接,因此接收方拿到的是文件本身而不是一段路径文本;同时附带纯文本路径,供编辑器使用。
- **把某一行拖到「文件转换 / 文件工具 / 文字识别」上**,就直接对这份用过的文件执行该操作——同一种手势反过来用。和所有拖放一样,它必须落在按钮上,拖回列表不会执行任何操作。
- 单击某一行在编辑器中打开;行内其余按钮负责发送、在文件夹中显示、以及钉在屏幕上。
## OCR
@ -294,7 +295,7 @@ Shift 会持续维护局域网内其他 Shift 实例的列表,并据此提供
## 软件更新
新的 macOS 机器请安装 **`Shift-0.1.8-macOS-universal.dmg`**:本项目的构建采用 ad-hoc 签名且未做公证,Gatekeeper 会把 Shift 判为身份不明的开发者。双击挂载镜像,把 `Shift.app` 拖进「应用程序」,然后允许首次启动一次(右键 → 打开,或在「系统设置 → 隐私与安全性」中点「允许」)。软件内升级自己下载的是同一个镜像、不经浏览器,因此不会弹窗。详见 `docs/RELEASE.md`。
新的 macOS 机器请安装 **`Shift-0.1.9-macOS-universal.dmg`**:本项目的构建采用 ad-hoc 签名且未做公证,Gatekeeper 会把 Shift 判为身份不明的开发者。双击挂载镜像,把 `Shift.app` 拖进「应用程序」,然后允许首次启动一次(右键 → 打开,或在「系统设置 → 隐私与安全性」中点「允许」)。软件内升级自己下载的是同一个镜像、不经浏览器,因此不会弹窗。详见 `docs/RELEASE.md`。
更新通道就是这个仓库:一条 `releases` 分支保存安装包以及 `shift-update.json` 清单,清单写明每个安装包的名称、体积与 SHA256。更新源地址在构建时由 git 远端推导——已适配 Gitea、GitHub、GitLab 三种形式,也可用 `SHIFT_UPDATE_URL` 覆盖——因此无需额外部署任何更新服务。
@ -316,7 +317,7 @@ Shift 每天启动时检查一次(也可在设置 → **软件更新** 中手
| ImageMagick `magick` | HEIC/HEIF/AVIF 输入与 HEIC 输出 | 不需要(`sips`) | 需要 | 需要 |
| LAME | 当 FFmpeg 缺少 `libmp3lame` 时的 MP3 编码 | 少见 | 少见 | 少见 |
Shift 会在设置 →「运行组件」中显示当前机器实际找到的工具、版本和路径,并可一键安装缺失的 Pandoc、Typst、FFmpeg、Poppler 与 ImageMagick。macOS 使用 Homebrew,Windows 使用 WinGet;安装后在界面中自动重新检测,无需重启。工具在调用时也会从 `PATH` 及系统常见安装目录查找,因此缺失某个依赖只会影响对应的扇区,不会影响整个应用。
Shift 会在设置 →「运行组件」中显示当前机器实际找到的工具、版本和路径,以及它们在本平台各自负责什么。显示为缺失的行同时给出出口:能装的都带**安装**按钮(macOS 通过 Homebrew 安装 Pandoc 与 FFmpeg;Windows 通过 WinGet 安装 Pandoc、FFmpeg、Poppler、ImageMagick 与 Typst),没有按钮的行说明该能力是内置的,或在本平台根本不会用到。安装后在界面中自动重新检测,无需重启。工具在调用时也会从 `PATH` 及系统常见安装目录查找,因此缺失某个依赖只会影响对应的扇区,不会影响整个应用。
## 平台支持情况
@ -328,7 +329,7 @@ Shift 会在设置 →「运行组件」中显示当前机器实际找到的工
| 跟随光标所在显示器 | 支持 | 支持 | `grim` 输出选择 |
| 区域录屏 | `screencapture -v`,`-g` 录麦克风 | FFmpeg `x11grab` | Wayland 用 `wf-recorder`,X11 用 FFmpeg `x11grab` |
| 录屏帧率控制 | 不提供(`screencapture` 不支持) | 15 / 24 / 30 | 15 / 24 / 30(`-r` / `-framerate`) |
| 截图历史库、把某一行拖出 | 支持 | 支持 | 支持 |
| 截图历史库、把某一行拖出与拖回按钮 | 支持 | 支持 | 支持 |
| 基于 git 的更新:SHA256 校验,清单可选签名 | 支持 | 发布的是 x64 安装包;ARM 机器经由 `windows` 回退拿到同一份 | 可检查并下载;Linux 没有发布产物,因此结果是「没有对应产物」 |
| 图片转换与编辑 | 支持 | 支持 | 支持 |
| HEIC / AVIF 编码 | `sips` | ImageMagick | ImageMagick |
@ -368,7 +369,7 @@ pnpm mac:release
scripts/build-windows-release.sh
```
发布链只产出两个安装包:`Shift-0.1.8-macOS-universal.dmg` 与 `Shift-Setup-0.1.8-win-x64.exe`。macOS 是单个通用 Mach-O,内含通用版的拖拽、PDF 渲染与文档渲染伴生进程;Windows ARM64 通过更新清单的兼容回退使用 x64 安装包。完整步骤见 `docs/BUILD_WINDOWS.md` 与 `docs/RELEASE.md`。
发布链只产出两个安装包:`Shift-0.1.9-macOS-universal.dmg` 与 `Shift-Setup-0.1.9-win-x64.exe`。macOS 是单个通用 Mach-O,内含通用版的拖拽、PDF 渲染与文档渲染伴生进程;Windows ARM64 通过更新清单的兼容回退使用 x64 安装包。完整步骤见 `docs/BUILD_WINDOWS.md` 与 `docs/RELEASE.md`。
**权限(macOS)。** 截图与录屏需要「屏幕录制」,输出目录需要「文件与文件夹」授权,带声音录屏需要「麦克风」,「发送到设备」需要「本地网络」。Shift 会在打开截图遮罩前先检查屏幕录制权限,因此被拒绝时给出的是可操作的提示,而不是一张全黑的截图。「本地网络」被拒绝时比较安静:Shift 仍会发出广播、也能回应主动找它的实例,但收不到组播,设备列表于是始终为空。ad-hoc 签名每次重新构建都会得到新的代码身份,而 macOS 正是按这个身份记录上述授权,所以升级后可能重新询问;改用 Developer ID 签名即可保持稳定。

View File

@ -1,4 +1,4 @@
Shift 0.1.8 - macOS 通用(universal)
Shift 0.1.9 - macOS 通用(universal)
本文件说明 macOS 安装包是怎么打出来的、在其它机器上会遇到什么,以及如何自己校验。
完整细节见仓库 docs/RELEASE.md 的「macOS packaging」和 docs/ENGINEERING-NOTES.md
@ -8,7 +8,7 @@ Shift 0.1.8 - macOS 通用(universal)
关于这个安装包
--------------
Shift 的 macOS 产物只有一个:Shift-0.1.8-macOS-universal.dmg,通用二进制,Apple silicon 与
Shift 的 macOS 产物只有一个:Shift-0.1.9-macOS-universal.dmg,通用二进制,Apple silicon 与
Intel 都能用。它既是新机器的首次安装方式,也是软件内升级的载体(更新清单里的 macos
键指向它)。清单的键必须是 .dmg,因为软件内升级的交接脚本要用 hdiutil 挂载镜像再
取出应用包;早期曾随包发布的 .pkg 在验证过 DMG 可用后就撤掉了,不为它多维护一份
@ -23,7 +23,7 @@ Intel 都能用。它既是新机器的首次安装方式,也是软件内升
----------------
新机器首次安装
1. 下载并双击 Shift-0.1.8-macOS-universal.dmg 挂载镜像。
1. 下载并双击 Shift-0.1.9-macOS-universal.dmg 挂载镜像。
2. 把 Shift.app 拖进「应用程序」(或任何你有权限的位置)。
3. 首次启动会被拦:「无法打开,因为来自身份不明的开发者」。点取消,然后
右键 Shift.app → 打开,或在「系统设置 → 隐私与安全性」中点「仍要打开」。
@ -70,7 +70,7 @@ macOS 权限
pnpm tauri build --target universal-apple-darwin --bundles app,dmg
`pnpm mac:release` 会构建、校验并复制为 artifacts/Shift-0.1.8-macOS-universal.dmg。
`pnpm mac:release` 会构建、校验并复制为 artifacts/Shift-0.1.9-macOS-universal.dmg。
发布流程(清单、签名、推送)见仓库 docs/RELEASE.md。
若希望更新通道能校验来源,构建时把 ed25519 公钥编进去(发布流程见仓库
@ -96,7 +96,7 @@ docs/RELEASE.md 的「Signing the channel」):
镜像完整性:
hdiutil verify Shift-0.1.8-macOS-universal.dmg
hdiutil verify Shift-0.1.9-macOS-universal.dmg
校验后仍打不开的话,请确认不是在压缩包预览窗口里运行的,并按上面的「新机器首次安装」
处理首次允许:右键 → 打开,或在「系统设置 → 隐私与安全性」中点「仍要打开」。

View File

@ -1,9 +1,10 @@
# Shift 工程回归台账
本文件记录 0.1.2 到 0.1.8 之间已经踩过、并且不应再次引入的工程问题,重点覆盖:
本文件记录 0.1.2 到 0.1.9 之间已经踩过、并且不应再次引入的工程问题,重点覆盖:
- Drop / 局域网设备发现
- DOCX、Markdown 与图片转换
- 设置面板与「运行组件」的显示口径
- macOS DMG 打包及在其它机器上的安装
它记录的是实现约束、故障原因和回归方法,不是用户手册。修改相关代码或打包配置前,
@ -20,6 +21,7 @@
| 0.1.6 | 增加按网卡定向广播,改善过滤组播的网络,但用户实测仍只能短暂看到设备。 |
| 0.1.7 | 增加单播扫描、普通信标回应、15 秒过期和 Windows 错误处理;用户实测 Mac 与 Windows 终端的 Drop 发现恢复正常。 |
| 0.1.8 | 最近文件改为收藏并移除拖回主操作按钮的交互;Windows 增加单实例保护;macOS DOCX→PDF 改用 Quick Look 源,保留页眉、页脚与装订版式。 |
| 0.1.9 | 重新支持把「最近使用」拖回三个主操作按钮,并且**按钮是唯一落点**——松开在面板其他位置不执行任何操作(见「『最近使用』拖回主面板的三个按钮」);设置面板字号统一到 `--text-*` 阶梯;取消「截图后」行为选项,固定为结果卡片;修复 macOS「运行组件」把 AppKit 文档渲染器报成 Pandoc 缺失且没有安装入口的回归。 |
历史提交可以这样定位:
@ -345,6 +347,92 @@ cargo test --lib capture
6. 圆环(拖文件到面板,或「文件转换」选文件后)→ `ESC` 收起圆环。
7. `Enter` 仍能确认选区并保存截图。
## 「运行组件」的显示口径
### 0.1.9 的 macOS 回归
macOS 的设置 → 运行组件里,文档转 PDF 那一行显示 **“Pandoc PDF pipeline / 缺失”**,
而且**没有安装按钮**。两件事都是同一个错误造成的。
`document_pdf_component()` 原本在 `if let Some(renderer) = files::doc_render_bridge()`
里 `return` 掉内置的 AppKit 渲染器;`df35111`(准备 0.1.8)把 `return` 改成了裸表达式,
于是构造出的组件被丢弃、继续往下走到 Pandoc 分支。后果是:
- 名字变成 `Pandoc PDF pipeline`,可用条件变成 `pandoc.is_some() && pdf_engine.is_some()`;
macOS 这条链路根本不需要 LaTeX/Typst 引擎(pandoc 只负责把带图 DOCX 转成 HTML 交给
渲染器),所以只要机器上没装 xelatex/typst 之类就永远显示缺失。
- 面板对 `external` 且缺失的行只给安装按钮,而 `install_target("document-pdf")` 在
macOS 没有条目(只有 `pandoc`、`media`),于是既报缺失又无处可装。
**修法不是补一个安装入口,而是恢复「macOS 由内置渲染器作答」这件事。** 现在两个平台各自
拥有独立的 `document_pdf_component()`(`#[cfg(target_os = "macos")]` /
`#[cfg(not(target_os = "macos"))]`),与同文件里 `pdf_page_component`、
`image_backend_component` 的写法一致:在 macOS 上想再次落到 Pandoc 分支会变成编译错误,
而不再是一次静默的行为回归。
### 不能随意改掉的约束
| 约束 | 原因 |
| --- | --- |
| macOS 的 `document-pdf` 必须是 `source = "bundled"` 且以 `doc_render_bridge()` 为准 | 这条转换在 macOS 上就是 Quick Look / AppKit 渲染器;改成 external 会重新引入"缺失但装不了"。 |
| 带图 DOCX 仍需要 Pandoc,但那是 `pandoc` 那一行的职责 | `pandoc` 行有自己的安装目标(`brew install pandoc`);不要把依赖合并进 `document-pdf`。 |
| `external` + 缺失的行必须有安装目标 | 否则面板等于告诉用户坏了、却不给出口,就是本次回归的表现。 |
### 回归测试
`src-tauri/src/runtime.rs` 的 `tests` 模块:
```bash
cd src-tauri
cargo test --lib runtime
```
- `macos_document_pdf_is_the_bundled_renderer_not_a_pandoc_pipeline`:钉住 macOS 的
`source` 与 `name`。
- `a_missing_component_always_offers_a_way_forward`:任何标记为缺失的行都必须要么可安装、
要么本来就不是 external。
## 「最近使用」拖回主面板的三个按钮
0.1.8 曾经把这条交互关掉:一行拖出去是文件,拖回来却什么都不是,用户只能重新选一次文件。
现在拖到「文件转换 / 文件工具 / 文字识别」上就执行该按钮的动作。
**按钮是唯一的落点。** 从 0.1.9 起,拖到面板其他位置**不执行任何操作**,只提示"请把文件拖到
下方三个按钮之一"。此前"落在面板空白处就打开操作环"的兜底已经去掉:外部拖入和内部拖拽都遵循
同一条规则,`dropFiles` 的 `action` 参数因此从 `DropAction | null` 收紧成 `DropAction`。拖拽
进行中三个按钮会同时点亮为候选落点(原生拖拽用 `dragging`,内部拖拽用 `rowDragging`),否则
用户在松开之前无从知道该瞄哪里。实现上有一条约束容易在重构时丢掉:
**一次内部拖拽可能被报告两次。** 历史行使用 `dragOutPayload`,也就是 `text/uri-list` 里的
`file://` 加纯文本路径,因此它对外就是一个文件拖拽。同一次手势有两种投递路径:
- DOM:`onDragOver` / `onDrop`(挂在 `.home` 根节点,用 `clientX/clientY` 命中按钮);
- 原生:`getCurrentWebview().onDragDropEvent` 的 `drop`(坐标要先经 `toWindowPoint` 换算)。
哪个先、是否都会到,取决于 WebView 版本与平台,所以两条路都必须武装,再由
`recentDrag.current = { path, landed }` 的 `landed` 标记只放行第一个。去掉这个标记,
圆环会被打开两次;只保留 DOM,Windows 的原生投递会让拖拽失效。
另外两条约束:
| 约束 | 原因 |
| --- | --- |
| `onDragEnd` 不能立即清空 `recentDrag`,要延迟 500 ms | 部分引擎在按钮抬起之后才发出原生 `drop`,提前清空会让这一次手势变成"落回面板的空拖拽"。 |
| 两条投递路径都必须把"没命中按钮"当作同一种结果处理 | 内部拖拽与外部拖入的语义必须一致;只在 DOM 路径拒绝、原生路径仍兜底开环,就会出现同一个动作两种结果。 |
| 点亮候选按钮的开关有两个来源 | 外部拖拽靠原生 `enter` 设置的 `dragging`,内部拖拽原生事件不一定到,必须另有 `rowDragging`,否则从列表拖起时按钮毫无反应。 |
### 回归测试
`src/lib/dropTargets.test.ts` 覆盖命中区域与坐标换算;拖拽本身用浏览器实测(Chromium 与
WKWebView 两条路径都要走一遍):
1. 「最近使用」某行 → 拖到「文件转换」→ 只弹出一个格式环,且文件是这一行。
2. 同一行 → 拖到「文件工具」→ 只弹出工具环。
3. 图片行 → 拖到「文字识别」→ 打开编辑器并自动开始识别;非图片行 → 退回格式环。
4. 同一行 → 拖到面板空白处 / 标题栏 / 列表本身 → 不开环、不执行,只提示需要拖到按钮上。
5. 从访达拖文件到面板空白处 → 同样不执行;拖到任一按钮 → 执行该按钮的动作。
6. 行拖出到访达/聊天窗口 → 仍是文件本体,没有被 Shift 自己吃掉。
## 修改这些路径时的统一回归命令
```bash

View File

@ -12,8 +12,8 @@ An orphan branch named `releases` holds exactly one release:
releases/
├── shift-update.json
├── shift-update.sig
├── Shift-0.1.8-macOS-universal.dmg
└── Shift-Setup-0.1.8-win-x64.exe
├── Shift-0.1.9-macOS-universal.dmg
└── Shift-Setup-0.1.9-win-x64.exe
```
`shift-update.json` names the version and, per platform, the artifact file, its size in
@ -22,12 +22,12 @@ bytes and its SHA256:
```json
{
"schema": 1,
"version": "0.1.8",
"version": "0.1.9",
"date": "2026-10-26",
"notes": "",
"artifacts": {
"macos": { "file": "Shift-0.1.8-macOS-universal.dmg", "sha256": "…", "size": 0 },
"windows": { "file": "Shift-Setup-0.1.8-win-x64.exe", "sha256": "…", "size": 0 }
"macos": { "file": "Shift-0.1.9-macOS-universal.dmg", "sha256": "…", "size": 0 },
"windows": { "file": "Shift-Setup-0.1.9-win-x64.exe", "sha256": "…", "size": 0 }
}
}
```

View File

@ -1,7 +1,7 @@
{
"name": "shift",
"private": true,
"version": "0.1.8",
"version": "0.1.9",
"type": "module",
"scripts": {
"prepare:ocr": "bash scripts/prepare-ocr-assets.sh",

2
src-tauri/Cargo.lock generated
View File

@ -3899,7 +3899,7 @@ dependencies = [
[[package]]
name = "shift"
version = "0.1.8"
version = "0.1.9"
dependencies = [
"base64 0.22.1",
"calamine",

View File

@ -1,6 +1,6 @@
[package]
name = "shift"
version = "0.1.8"
version = "0.1.9"
description = "A radial file utility with screenshot, recording and OCR."
authors = ["Shift Contributors"]
edition = "2021"

View File

@ -1,7 +1,7 @@
{
"$schema": "https://schema.tauri.app/config/2",
"productName": "Shift",
"version": "0.1.8",
"version": "0.1.9",
"identifier": "app.nex.shift",
"build": {
"beforeDevCommand": "pnpm dev",