From 7a345376abb9f5691f0c321f1db990ea794cebee Mon Sep 17 00:00:00 2001 From: shawn Date: Sun, 28 Jun 2026 00:05:10 +0800 Subject: [PATCH 1/3] docs: add MIT license --- LICENSE | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..6fc1bf9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 rrbe + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. From 792e0823705a310b1aa3624fe5217825566e2bec Mon Sep 17 00:00:00 2001 From: shawn Date: Sun, 28 Jun 2026 00:05:10 +0800 Subject: [PATCH 2/3] docs: rework readme for discoverability and text transfer --- README.md | 63 +++++++++++++++++++++++++++++++++++--------------- README_CN.md | 65 +++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 91 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 575eff8..a735c33 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,11 @@ -# LocalShare (LAN file sharing) +# LocalShare — share Mac files, scan a QR code to view or save them in your phone's browser [简体中文](README_CN.md) | English -A small macOS tool that spins up a static file server so you can share specific files/folders from your Mac with other devices on the same local network. +A small macOS app that moves files and text between your Mac and other devices (phone, tablet…) over WiFi — the other end just uses a browser, with no client to install. + +- Pick a file or folder, scan the QR code that appears (or just open the link), and browse the files in your phone's browser (HTML, PDF, Markdown, images…) +- Two-way text transfer — type some text and share it via a QR code, or send text back from the phone to the Mac @@ -14,31 +17,28 @@ A small macOS tool that spins up a static file server so you can share specific ## Features -- Share via QR code — scan with the Camera app to open in a browser -- Share multiple files / folders at once -- Serves HTML / PDF / video / images; previews Markdown / JSON / CSV right in the browser -- Optional guest upload (read-only by default) — send photos and documents from your phone back to the Mac -- Shows who's currently viewing (device name when it can be resolved, otherwise the IP) -- Optional "visible on current network only" — open on the current Wi-Fi only, unreachable from other networks the Mac is connected to -- Automatic updates (prompts when a new version is found; installs only after you confirm) +- Share files and text by QR code, or just by opening the link +- Serves HTML / PDF / video / images; previews Markdown / JSON / CSV +- After you share, the other end can send files and text back +- Shows who's currently viewing - `localshare` command line: bring up the window to share, or `--headless` to print the link and QR code in the terminal ## Why this app exists -- iPhone Safari can't open local HTML files directly — they need to be served from a static file server to preview -- When you don't want to actually move files to your phone via AirDrop/LocalSend, you just want to preview them there -- When you want to browse several files at once -- To share files with other people on the same LAN +- When AirDrop is flaky, or the other device isn't an Apple device +- iPhone Safari can't open local HTML files directly, so previewing the web pages you vibe-coded is awkward +- No need to spin up `python3 -m http.server` +- No need to install a client like LocalSend +- Preview only — no need to actually save files onto the phone +- Quickly pass text around, without relying on flaky Handoff -## Usage +## GUI usage -1. Open the app and drag files onto the window, or click "Choose Files or Folders". -2. Connect your phone to **the same Wi-Fi as the Mac**, then scan the QR code in the window with the Camera app. -3. If macOS shows a firewall prompt on first launch, click "Allow". +Scan the QR code, or open the LAN address directly. If macOS shows a firewall prompt on first launch, click "Allow". The QR code points to something like `http://192.168.x.x:8080/?t=`: the link carries a one-time token, so whoever scans it gets in seamlessly, while anyone who only knows the IP:port cannot access it. -> ⚠️ Traffic is plain HTTP (unencrypted). That's fine on trusted networks like home or office; but on public Wi-Fi such as cafés or airports, others on the same network may be able to see what's transferred — don't share sensitive files there. When needed, turn on "visible on current network only" in the window to narrow the exposure. +> ⚠️ Traffic is plain HTTP (unencrypted). Best avoided on public networks like airports and cafés. ## Terminal usage @@ -65,6 +65,33 @@ The app is ad-hoc signed, so **opening** it may be blocked by Gatekeeper (warnin xattr -dr com.apple.quarantine /Applications/LocalShare.app ``` +## FAQ + +**How do I open a local HTML file on my iPhone?** +iPhone Safari can't open `file://` HTML directly. Share the file (or its folder) with LocalShare and scan the QR code — Safari opens it from the local server, so links, CSS and images resolve normally. + +**Does the other device need to install anything?** +No. Anything with a camera and a browser works — iPhone, iPad, Android, another Mac. Only the sharing Mac runs LocalShare. + +**Does it need internet?** +No. Everything stays on your local network (the Mac and phone just need the same WiFi); nothing goes through the cloud. + +**Is it secure?** +The link carries a one-time token, so knowing the IP:port isn't enough to get in. Traffic is plain HTTP, which is fine on a home/office network — avoid sharing sensitive files on public WiFi, and turn on "visible on current network only" to narrow exposure. + +**Can the phone send files back to the Mac?** +Yes, if you turn on guest upload (off by default). Then the phone can upload photos and documents into the shared folder. + +**Can I send a link or some text to my phone?** +Yes. Paste the text on the Mac and share it the same way — your phone opens it in the browser with a Copy button. You can also turn on the text inbox (off by default) so the phone can send text back to the Mac. + +**Windows or Linux?** +LocalShare is macOS-only. On other platforms, dufs or LocalSend cover similar needs. + +## License + +MIT — see [LICENSE](LICENSE). + ## Credits This project was inspired by: diff --git a/README_CN.md b/README_CN.md index ce5f3de..be5b7ab 100644 --- a/README_CN.md +++ b/README_CN.md @@ -1,8 +1,11 @@ -# LocalShare（局域网文件分享） +# LocalShare —— 共享 Mac 文件，扫码在手机浏览器里查看/保存 简体中文 | [English](README.md) -一个 macOS 小工具，启动一个静态文件托管服务，分享你电脑上的特定文件/文件夹，在同一个局域网下的其他设备中访问。 +一个 macOS 小工具，在本机和手机等设备之间通过 WiFi 互通文件和文本，对端使用浏览器，无须安装客户端。 + +- 选中文件或文件夹，相机扫描出现的二维码，或直接打开链接，在手机浏览器里浏览这些文件（HTML、PDF、Markdown、图片……） +- 支持双向传送文本，编辑文字通过二维码分享后传输，并可从手机端发送文本回 Mac
@@ -14,31 +17,28 @@ ## 功能 -- 二维码分享，相机 app 扫一下浏览器中打开 -- 一次分享多个文件 / 文件夹 -- 支持 HTML / PDF / 视频 / 图片，Markdown / JSON / CSV 在浏览器里直接预览 -- 可选开启访客上传（默认只读），手机里的照片、文档能传回电脑 -- 显示当前在线访客（能反查到就显示设备名，否则显示 IP 尾号） -- 可选「仅当前网络可见」：只在当前 WiFi 开放，电脑连着的其它网络访问不到 -- 自动更新（发现新版会提示，确认后再装） -- 命令行 localshare：唤起窗口分享，或 --headless 在终端显示链接和二维码 +- 二维码分享或直接打开链接分享文件、文本 +- 支持 HTML / PDF / 视频 / 图片，Markdown / JSON / CSV 预览 +- 支持分享后，由对端反向传输文件、文本 +- 显示当前在线访客 +- 命令行 `localshare` 命令：唤起窗口分享，或 `--headless` 在终端显示链接和二维码 ## 为什么有这个 app -- iPhone 不支持 html 文件直接在手机 Safari 中打开，需要托管到静态文件服务器才能预览 -- 如果你并不想把文件通过 AirDrop/LocalSend 传到手机，只是想在手机预览 -- 想同时浏览多个文件 -- 分享文件给局域网内的其他人使用 +- 避免 AirDrop 的不稳定，或对端并非苹果设备 +- iPhone 不支持 html 文件直接在手机 Safari 中打开，不便预览你 Vibe Coding 的网页 +- 不需要配置 python 启动 `python3 -m http.server` +- 不需要安装 LocalSend 等客户端 +- 可以只预览，不需要传递文件到手机存储 +- 快速传递文本，避免 handoff 不稳定 -## 使用 +## GUI 使用 -1. 打开 app，拖拽文件到 app 窗口，或手动点「选择文件夹/单个文件」。 -2. 手机连上**与电脑相同的 WiFi**，用相机扫描窗口里的二维码。 -3. 首次启动若系统弹出防火墙提示，点「允许」。 +扫描二维码或通过局域网连接地址打开，首次启动若系统弹出防火墙提示，点「允许」。 二维码地址形如 `http://192.168.x.x:8080/?t=随机令牌`：链接里带一次性令牌，扫码者无感进入，单纯知道 IP:端口 的人无法访问。 -> ⚠️ 传输是明文 HTTP（没有加密）。在家里 / 公司这种可信网络下没问题；但在咖啡馆、机场等公共 WiFi 下，同一网络的人有可能看到传输内容——别在这种网络分享敏感文件。需要时可在窗口里开「仅当前网络可见」收窄暴露面。 +> ⚠️ 传输是明文 HTTP（没有加密）。机场咖啡厅等公共网络下最好不要使用。 ## 终端用法 @@ -65,6 +65,33 @@ ad-hoc 签名，**打开**可能被 Gatekeeper 拦截（提示「已损坏」或 xattr -dr com.apple.quarantine /Applications/LocalShare.app ``` +## 常见问题 + +**怎么在 iPhone 上打开本地 HTML 文件？** +iPhone Safari 不能直接打开 `file://` 的 HTML。用 LocalShare 分享这个文件（或它所在的文件夹），扫码即可——Safari 从本地服务打开它，链接、CSS、图片都能正常解析。 + +**对方设备需要装什么吗？** +不用。有相机和浏览器就行——iPhone、iPad、安卓、另一台 Mac 都可以。只有分享方的 Mac 跑 LocalShare。 + +**需要联网吗？** +不需要。一切都在本地网络里（Mac 和手机连同一个 WiFi 即可），不经过云端。 + +**安全吗？** +链接带一次性令牌，光知道 IP:端口 进不来。传输是明文 HTTP，在家里 / 公司网络下没问题——别在公共 WiFi 分享敏感文件，需要时开「仅当前网络可见」收窄暴露面。 + +**手机能把文件传回 Mac 吗？** +可以。开启访客上传后（默认关闭），手机就能把照片、文档传进被分享的文件夹。 + +**能把链接或一段文字发到手机上吗？** +可以。在 Mac 上粘好文字，照样分享出去——手机在浏览器里打开，带一个「复制」按钮。也可以开启文本收件箱（默认关闭），让手机把文本发回 Mac。 + +**Windows 或 Linux 能用吗？** +LocalShare 只支持 macOS。其它平台上 dufs 或 LocalSend 能覆盖类似需求。 + +## 协议 + +MIT —— 见 [LICENSE](LICENSE)。 + ## 参考项目 本项目受到如下项目的启发 From a855af8112568213459bd1405d3e4bac06a3559b Mon Sep 17 00:00:00 2001 From: shawn Date: Sun, 28 Jun 2026 00:15:05 +0800 Subject: [PATCH 3/3] docs: drop redundant readme FAQ section --- README.md | 23 ----------------------- README_CN.md | 23 ----------------------- 2 files changed, 46 deletions(-) diff --git a/README.md b/README.md index a735c33..e153bb3 100644 --- a/README.md +++ b/README.md @@ -65,29 +65,6 @@ The app is ad-hoc signed, so **opening** it may be blocked by Gatekeeper (warnin xattr -dr com.apple.quarantine /Applications/LocalShare.app ``` -## FAQ - -**How do I open a local HTML file on my iPhone?** -iPhone Safari can't open `file://` HTML directly. Share the file (or its folder) with LocalShare and scan the QR code — Safari opens it from the local server, so links, CSS and images resolve normally. - -**Does the other device need to install anything?** -No. Anything with a camera and a browser works — iPhone, iPad, Android, another Mac. Only the sharing Mac runs LocalShare. - -**Does it need internet?** -No. Everything stays on your local network (the Mac and phone just need the same WiFi); nothing goes through the cloud. - -**Is it secure?** -The link carries a one-time token, so knowing the IP:port isn't enough to get in. Traffic is plain HTTP, which is fine on a home/office network — avoid sharing sensitive files on public WiFi, and turn on "visible on current network only" to narrow exposure. - -**Can the phone send files back to the Mac?** -Yes, if you turn on guest upload (off by default). Then the phone can upload photos and documents into the shared folder. - -**Can I send a link or some text to my phone?** -Yes. Paste the text on the Mac and share it the same way — your phone opens it in the browser with a Copy button. You can also turn on the text inbox (off by default) so the phone can send text back to the Mac. - -**Windows or Linux?** -LocalShare is macOS-only. On other platforms, dufs or LocalSend cover similar needs. - ## License MIT — see [LICENSE](LICENSE). diff --git a/README_CN.md b/README_CN.md index be5b7ab..a8f886e 100644 --- a/README_CN.md +++ b/README_CN.md @@ -65,29 +65,6 @@ ad-hoc 签名，**打开**可能被 Gatekeeper 拦截（提示「已损坏」或 xattr -dr com.apple.quarantine /Applications/LocalShare.app ``` -## 常见问题 - -**怎么在 iPhone 上打开本地 HTML 文件？** -iPhone Safari 不能直接打开 `file://` 的 HTML。用 LocalShare 分享这个文件（或它所在的文件夹），扫码即可——Safari 从本地服务打开它，链接、CSS、图片都能正常解析。 - -**对方设备需要装什么吗？** -不用。有相机和浏览器就行——iPhone、iPad、安卓、另一台 Mac 都可以。只有分享方的 Mac 跑 LocalShare。 - -**需要联网吗？** -不需要。一切都在本地网络里（Mac 和手机连同一个 WiFi 即可），不经过云端。 - -**安全吗？** -链接带一次性令牌，光知道 IP:端口 进不来。传输是明文 HTTP，在家里 / 公司网络下没问题——别在公共 WiFi 分享敏感文件，需要时开「仅当前网络可见」收窄暴露面。 - -**手机能把文件传回 Mac 吗？** -可以。开启访客上传后（默认关闭），手机就能把照片、文档传进被分享的文件夹。 - -**能把链接或一段文字发到手机上吗？** -可以。在 Mac 上粘好文字，照样分享出去——手机在浏览器里打开，带一个「复制」按钮。也可以开启文本收件箱（默认关闭），让手机把文本发回 Mac。 - -**Windows 或 Linux 能用吗？** -LocalShare 只支持 macOS。其它平台上 dufs 或 LocalSend 能覆盖类似需求。 - ## 协议 MIT —— 见 [LICENSE](LICENSE)。