diff --git a/.github/workflows/repository-hygiene.yml b/.github/workflows/repository-hygiene.yml index 9d47e02..9b1cd4f 100644 --- a/.github/workflows/repository-hygiene.yml +++ b/.github/workflows/repository-hygiene.yml @@ -7,7 +7,7 @@ on: workflow_dispatch: inputs: client_checks: - description: Run the optional Piik Client checks + description: Run the optional Piik App checks required: false default: false type: boolean @@ -83,7 +83,7 @@ jobs: - name: Upload application release uses: actions/upload-artifact@v7 with: - name: piik-app-${{ github.sha }} + name: piik-server-${{ github.sha }} path: ${{ runner.temp }}/app-release/* if-no-files-found: error retention-days: 14 @@ -125,7 +125,7 @@ jobs: go-version: 1.26.6 cache-dependency-path: go.sum # scripts/assemble-client.mjs runs `npm run build:client` for the Web - # assets the Client binary embeds, so Vite and the license inputs must be + # assets the App binary embeds, so Vite and the license inputs must be # installed here too. - name: Install dependencies run: npm ci @@ -142,18 +142,18 @@ jobs: - name: Download application release uses: actions/download-artifact@v8 with: - name: piik-app-${{ github.sha }} + name: piik-server-${{ github.sha }} path: ${{ runner.temp }}/app-release - - name: Build and verify Client candidate + - name: Build and verify App candidate run: >- node scripts/package-client-candidate.mjs "${{ runner.temp }}/app-release" "${{ matrix.target }}" "${{ runner.temp }}/client-release" - - name: Upload Client release candidate + - name: Upload App release candidate uses: actions/upload-artifact@v7 with: - name: piik-client-${{ matrix.target }}-${{ github.sha }} + name: piik-app-${{ matrix.target }}-${{ github.sha }} path: ${{ runner.temp }}/client-release/* if-no-files-found: error compression-level: 0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e67ffc..883a3e7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,6 +51,10 @@ Clean up worktrees and branches only after semantic review and integration are c ## Research Standard +Follow the [naming convention](./docs/reference/naming.md) for product copy, +commands, packages and code ownership. Keep display names separate from stable +protocol identifiers; use normal language-specific identifier conventions. + - Prefer specifications, official product documentation, primary source code, maintainers' design notes, and original papers. - Use current community issues and operational reports to identify real compatibility failures, but label anecdotal evidence as such. - Include a date and direct URLs. Separate verified facts, measurements, assumptions, and recommendations. diff --git a/README.md b/README.md index 3679684..ba6a51f 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Friends watch in their browsers, with no installation. ```mermaid flowchart LR Browser[Browser] --> Host[Host a room] - Client[Piik Client] --> Host + App[Piik App] --> Host Host -->|Invite link| Friends[Friends watch in browsers] ``` @@ -34,29 +34,29 @@ Capture needs HTTPS or `localhost`; available sources and sound depend on the browser and platform. English, Chinese and an illustrated visual mode share the same controls, with light and dark themes. -## Start your own room with Client +## Start your own room with Piik App -With a Client package for your platform: +With the Piik App package for your platform: 1. Extract the whole package, keeping `runtime` beside the executable. -2. Open `piik-client.exe` on Windows, `Piik Client.app` on macOS, or - `./piik-client` on Linux. -3. Choose a mode, pick what to share, and send the invitation. Keep Client running. +2. Open `piik-app.exe` on Windows, `Piik App.app` on macOS, or + `./piik-app` on Linux. +3. Choose a mode, pick what to share, and send the invitation. Keep the app running. | Mode | Use it for | | --- | --- | | **Local room** | Friends on the same local network. An optional site password controls access. | -| **Public invite** | A temporary Internet invitation. The link lasts for this Client run; media remains P2P. | -| **Connect to Site** | An existing Piik site, with Client capture and media capabilities available in the same browser UI. | +| **Public invite** | A temporary Internet invitation. The link lasts for this App run; media remains P2P. | +| **Connect to Site** | An existing Piik site, with App capture and media capabilities available in the same browser UI. | -Client opens your system browser. Its package includes the Go application and +Piik App opens your system browser. Its package includes the Go application and capture/link helpers; running it needs no Node.js, npm or Go installation. Linux native capture uses the system Portal, PipeWire and GStreamer stack. -See the [Client guide](./cmd/piik-client/README.md) for platform details. +See the [App guide](./cmd/piik-app/README.md) for platform details. Temporary public links use Cloudflare Quick Tunnel, which has no uptime guarantee. Media needs a working UDP path; restrictive networks or browser/OS suspension -can interrupt sharing. Windows Client and Browser are the current acceptance +can interrupt sharing. Windows App and Browser are the current acceptance focus; macOS/Linux physical capture checks remain separate. See [current status](./docs/status.md) for candidate and release readiness. @@ -72,10 +72,10 @@ For source builds, tests and architecture, start with the ## Something went wrong? Include your version, OS/browser, expected result and steps to reproduce. -For a local report, start Client with `--debug` and press `D`, or add `?debug=1` +For a local report, start Piik App with `--debug` and press `D`, or add `?debug=1` before any `#` in the Browser page URL and use its header download button. Review reports before sharing; see [diagnostics and export](./docs/reference/configuration.md#diagnostics). -Connection trouble? Try the [Chromium WebRTC FAQ](./cmd/piik-client/README.md#chromium-webrtc-connections). +Connection trouble? Try the [Chromium WebRTC FAQ](./cmd/piik-app/README.md#chromium-webrtc-connections). ## License diff --git a/README.zh-CN.md b/README.zh-CN.md index 4e463bd..d47ee0d 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -12,7 +12,7 @@ Piik 是一个私密屏幕分享工具：一位房主，最多 20 位受邀好 ```mermaid flowchart LR Browser[浏览器] --> Host[开房分享] - Client[Piik Client] --> Host + App[Piik App] --> Host Host -->|邀请链接| Friends[好友用浏览器观看] ``` @@ -33,28 +33,28 @@ flowchart LR 浏览器采集需要 HTTPS 或 `localhost`；可选来源和声音支持取决于浏览器与平台。 界面提供中文、英文和图示模式，以及明暗主题。 -## 用 Client 自己开房 +## 用 App 自己开房 -拿到对应平台的 Client 程序包后： +拿到对应平台的 App 程序包后： 1. 完整解压，保留可执行文件旁的 `runtime` 目录。 -2. Windows 打开 `piik-client.exe`，macOS 打开 `Piik Client.app`， - Linux 运行 `./piik-client`。 -3. 选择模式和分享来源，发出邀请。分享期间保持 Client 运行。 +2. Windows 打开 `piik-app.exe`，macOS 打开 `Piik App.app`， + Linux 运行 `./piik-app`。 +3. 选择模式和分享来源，发出邀请。分享期间保持 App 运行。 | 模式 | 适合什么情况 | | --- | --- | | **本地房间** | 与同一局域网内的好友分享，可设置站点访问密码。 | -| **公网邀请** | 生成本次 Client 运行期间有效的临时邀请链接；媒体仍走 P2P。 | -| **连接站点** | 使用已有 Piik 站点，并在同一浏览器界面使用 Client 的采集与媒体能力。 | +| **公网邀请** | 生成本次 App 运行期间有效的临时邀请链接；媒体仍走 P2P。 | +| **连接站点** | 使用已有 Piik 站点，并在同一浏览器界面使用 App 的采集与媒体能力。 | -Client 会打开系统浏览器。程序包包含 Go 应用和采集、临时链接辅助程序， +App 会打开系统浏览器。程序包包含 Go 应用和采集、临时链接辅助程序， 运行时无须安装 Node.js、npm 或 Go。Linux 原生采集使用系统的 Portal、PipeWire -和 GStreamer，平台细节见 [Client 指南](./cmd/piik-client/README.md)。 +和 GStreamer，平台细节见 [App 指南](./cmd/piik-app/README.md)。 临时公网链接使用 Cloudflare Quick Tunnel，不保证持续可用。 媒体需要可用的 UDP 路径；网络限制、浏览器或系统挂起都可能中断分享。 -当前以 Windows Client 和浏览器为验收重点，macOS/Linux 原生采集的实机验证另行进行。 +当前以 Windows App 和浏览器为验收重点，macOS/Linux 原生采集的实机验证另行进行。 候选版本与发布准备情况见 [当前状态](./docs/status.md)。 ## 自建站点或参与开发 @@ -68,10 +68,10 @@ SFU 后备路径。搭建自己的站点，请看 [自托管指南](./docs/opera ## 遇到问题？ 反馈时附上版本、系统与浏览器、预期结果和复现步骤。 -Client 可用 `--debug` 启动后按 `D` 导出本地报告；浏览器网址加上 `?debug=1` +App 可用 `--debug` 启动后按 `D` 导出本地报告；浏览器网址加上 `?debug=1` 后（放在 `#` 之前），可点击顶部下载按钮。分享前请检查报告内容，详见 [诊断与导出](./docs/reference/configuration.md#diagnostics)。 -连接不上时，也可以查看 [Chromium WebRTC 常见问题](./cmd/piik-client/README.md#chromium-webrtc-connections)。 +连接不上时，也可以查看 [Chromium WebRTC 常见问题](./cmd/piik-app/README.md#chromium-webrtc-connections)。 ## 许可 diff --git a/cmd/piik-client/README.md b/cmd/piik-app/README.md similarity index 84% rename from cmd/piik-client/README.md rename to cmd/piik-app/README.md index c2adab7..c37a393 100644 --- a/cmd/piik-client/README.md +++ b/cmd/piik-app/README.md @@ -1,38 +1,38 @@ -# Piik Client +# Piik App -Piik Client is the self-contained and native-capability runtime for the same +Piik App is the self-contained and native-capability runtime for the same Browser application used by Hosted Piik. It does not implement another UI, room store, signaling protocol, or route controller. ## Run A Package Extract the matching platform bundle in full and keep `runtime` beside the -Client executable. Run `piik-client.exe` on Windows, `./piik-client` on -Linux, or `Piik Client.app` on macOS. The launcher opens in the system Browser; -the Client does not embed a browser UI. Packaged execution needs no Node.js, npm, +App executable. Run `piik-app.exe` on Windows, `./piik-app` on +Linux, or `Piik App.app` on macOS. The launcher opens in the system Browser; +the App does not embed a browser UI. Packaged execution needs no Node.js, npm, or Go installation. Linux native capture uses the system dependencies described in the [Linux capture guide](../../native/capture/linux/README.md). -Windows Client and Browser are this phase's acceptance targets. Other platform +Windows App and Browser are this phase's acceptance targets. Other platform builds do not establish physical capture/audio acceptance; see [current status](../../docs/status.md). Package construction and public Release publication are separate steps in [deployment](../../docs/deployment.md). ## Modes -- With no mode argument, the Client opens a small launcher in the system +- With no mode argument, the App opens a small launcher in the system Browser. It selects Local, a temporary public HTTPS invitation, or a saved Site, then enters the normal Host page. - The launcher remembers the Site address but keeps the per-run room source - separate. The Client RPC starts before this choice and accepts the saved Site + separate. The App RPC starts before this choice and accepts the saved Site alongside the Local Host origin, so Local or Public invite does not disable - Site enhancement. A Client-opened Site remembers the opt-in in that Browser - origin; later manually opened Host pages may reuse the running Client. + Site enhancement. An App-opened Site remembers the opt-in in that Browser + origin; later manually opened Host pages may reuse the running App. - `--site`, `--local`, and `--link` remain deterministic automation inputs for CI and development. They are not required for normal use. - The default launcher checks the official GitHub Releases metadata after it opens and shows a notice when a newer full-SHA release exists. The check is - best-effort and never installs or replaces the Client. + best-effort and never installs or replaces the App. Local mode uses memory-only rooms, P2P relay, no SFU listener, and no public discovery. Ordinary Local works on a reachable LAN. The **Public invite** mode @@ -42,10 +42,10 @@ uses one ordinary public STUN destination plus two bounded public survey destinations. Browser and Native edges share the same prediction rule; Native STUN, ICE checks, and media use one Pion UDP mux. Media does not travel through the HTTP tunnel, and a difficult media path still has no SFU or -TURN fallback. The Client chooses a sole private LAN IPv4 automatically. Use +TURN fallback. The App chooses a sole private LAN IPv4 automatically. Use `--lan-address
` only when multiple real LAN interfaces are active. -The system Browser remains the Host UI. A Client-launched Host offers the +The system Browser remains the Host UI. An App-launched Host offers the Browser's standard capture picker and a list of exact platform capture targets; the user selects one explicitly. Windows offers the same VP8/Auto/H264 selector: VP8 uses the pinned WebRTC/libvpx encoder and H264 uses hardware Media Foundation @@ -61,10 +61,10 @@ live changes replace only the capture/encoder generation behind those stable connections. A Native edge with public STUN also attempts one bounded PCP, UPnP, or NAT-PMP mapping for its Pion UDP socket; pure LAN does not. Routers without a mapping service continue with ordinary ICE/STUN. The mapping does not -create a relay or carry media through the Client control link. A configured Site +create a relay or carry media through the App control link. A configured Site may receive a direct Native publication from the shared encoded source; Local and one-link modes remain P2P-only. An ordinary Web Host keeps the -Browser capture path without probing the Client. +Browser capture path without probing the App. Native P2P edges and embedded SFU use one shared Pion/LiveKit media adapter for feedback, forwarding allocation, bounded pacing and recovery. Native parents @@ -78,22 +78,22 @@ there is no room-wide score or periodic rebalance. See [media quality](../../docs/product/media-quality.md) for the implemented behavior and [status](../../docs/status.md) for its acceptance limits. -The Client configuration keeps an optional Local site-access password. Leave it +The App configuration keeps an optional Local site-access password. Leave it blank for an open Local site, or set a visible-ASCII password (8 to 128 bytes) -in the launcher before starting. When present, the Client passes it to its own +in the launcher before starting. When present, the App passes it to its own Host page in a URL fragment; the page uses the existing SiteAccess endpoint and removes the fragment before continuing. Viewer invitations keep using the existing room-scoped grant. The terminal shows the current mode, entry links and startup state; its language -follows the launcher and Client-enabled pages. +follows the launcher and App-enabled pages. Press `o` to reopen the Browser, or `q` / Ctrl+C to end Local rooms and stop the local server and temporary public link. Plain-text output -uses Ctrl+C. A Site-loaded Browser tab does not own the Client process. +uses Ctrl+C. A Site-loaded Browser tab does not own the App process. -For one-link Internet sharing, open the Client launcher, choose **Public invite**, +For one-link Internet sharing, open the App launcher, choose **Public invite**, create a room in the opened Browser, and send its normal invitation link. The -random `trycloudflare.com` origin lasts only for that Client run; a later launch +random `trycloudflare.com` origin lasts only for that App run; a later launch creates a new temporary link. Cloudflare Quick Tunnels provide no uptime guarantee; use a configured Site when persistent control availability or SFU fallback matters. @@ -105,7 +105,7 @@ use a configured Site when persistent control availability or SFU fallback matte Chromium-based Browsers can restrict WebRTC UDP through Browser settings, extensions or managed policies. Disabling non-proxied UDP can prevent even the -local Browser-to-Client media connection; successful capture or page loading +local Browser-to-App media connection; successful capture or page loading does not prove that this separate connection is available. This is not specific to one Browser brand or to VPN use. @@ -139,7 +139,7 @@ The binary embeds the Browser assets, so build them before running it: npm run build:client go test ./... go vet ./... -go run ./cmd/piik-client +go run ./cmd/piik-app ``` The repository-level entry used locally and by CI is: @@ -148,13 +148,13 @@ The repository-level entry used locally and by CI is: npm run check:client ``` -On Windows, its generated Client, capture, and media-test executables are +On Windows, its generated App, capture, and media-test executables are written to the ignored repository `build/client-check` directory and reused on the next run. This keeps the executable identity stable for the system firewall; the files are local build output and are never packaged or committed. It runs Go formatting, unit tests, vet, and Windows/Linux cgo-free cross-builds. -The Darwin Client and peer gate build only on macOS with cgo enabled and an +The Darwin App and peer gate build only on macOS with cgo enabled and an installed SDK; other hosts report that skipped platform explicitly. The pinned media dependency's Darwin CPU statistics use Mach APIs through cgo, so a Windows or Linux core check does not establish Darwin build acceptance. @@ -173,14 +173,14 @@ one session retires only its resources. Its public `instanceToken` distinguishes the discovered process but is not authentication; room authority and remote signaling remain in the Browser. Viewer receive/relay remains available even when this machine has no accepted native capture encoder. -Capture sidecars must match the Client's current probe/encoded-output contract; +Capture sidecars must match the App's current probe/encoded-output contract; the package-candidate wrapper validates that version before accepting its artifact. ## Packaging From a clean revision, build the application release and run the platform's candidate wrapper on its native operating system. The wrapper builds capture, -verifies the pinned public-link helper, and assembles and checks the Client: +verifies the pinned public-link helper, and assembles and checks the App: ```sh node scripts/package-app-release.mjs /outside/repository/app-release @@ -200,11 +200,11 @@ explicit CI packaging, Release publication and updates are documented in The extracted bundle contains: ```text -piik-client[.exe] +piik-app[.exe] REVISION LICENSE THIRD-PARTY-NOTICES.txt -runtime/native/piik-client-capture[.exe] # supported native-media packages +runtime/native/piik-capture[.exe] # supported native-media packages runtime/tunnel/cloudflared[.exe] # packages that support --link ``` @@ -212,15 +212,15 @@ The executable embeds the Browser assets of the consumed application release and carries that same full Git revision as the package `REVISION`. No compatibility reader accepts a mismatched private build. -The Windows Client embeds the shared Piik mark through the -`cmd/piik-client/piik_windows_amd64.syso` resource; the platform +The Windows App embeds the shared Piik mark through the +`cmd/piik-app/piik_windows_amd64.syso` resource; the platform suffix keeps that Windows resource out of Linux and macOS builds. Linux packages include the standard `share/applications` desktop entry and -hicolor icon. macOS packages include a thin `Piik Client.app` launcher +hicolor icon. macOS packages include a thin `Piik App.app` launcher with an ICNS resource; the raw Go executable remains available beside it. -For a native Host smoke run, launch the Client and select a window in the Host -page. The Client never guesses among multiple targets. The page still creates +For a native Host smoke run, launch the App and select a window in the Host +page. The App never guesses among multiple targets. The page still creates the room and sends the current SDP/ICE through the selected authority. A configured Site supplies its normal Internet routing and SFU fallback. Without a Site, the **Public invite** choice exposes the Local control surface while @@ -237,13 +237,13 @@ is POSIX; use equivalent variables on Windows. ```sh PIIK_CLIENT_LOCAL_GATE=true \ CHROME_PATH=/path/to/chrome \ -PIIK_CLIENT_EXE=/path/to/piik-client \ +PIIK_CLIENT_EXE=/path/to/piik-app \ PIIK_CLIENT_GATE_LAN_ADDRESS=192.168.1.10 \ npm run gate:client-local PIIK_CLIENT_LOOPBACK_GATE=true \ CHROME_PATH=/path/to/chrome \ -PIIK_CLIENT_EXE=/path/to/piik-client \ +PIIK_CLIENT_EXE=/path/to/piik-app \ npm run probe:client-loopback PIIK_CLIENT_MEDIA_GATE=true \ @@ -293,7 +293,7 @@ delivery through the current route; native audio is included when the capability probe and target OS support it. The cross-NAT variant uses a temporary reverse SSH path for signaling only and requires a selected `srflx` or `prflx` media pair; media never travels through SSH. The one-link media variant instead carries the -same signaling through the Client's temporary public origin and requires direct +same signaling through the App's temporary public origin and requires direct media delivery to an independent Linux peer. Native P2P quality evidence and embedded SFU delivery have explicit gates. macOS and Linux capture still require physical desktop/media gates; CI compilation and package smoke do not diff --git a/cmd/piik-client/main.go b/cmd/piik-app/main.go similarity index 74% rename from cmd/piik-client/main.go rename to cmd/piik-app/main.go index bee3ae6..e55bca0 100644 --- a/cmd/piik-client/main.go +++ b/cmd/piik-app/main.go @@ -1,7 +1,7 @@ -// Command piik-client is the self-contained Piik Client: it opens a +// Command piik-app is the self-contained Piik App: it opens a // configured Piik Site, or runs the Local room authority in-process // (--local / --link) together with the loopback capability service and the -// native media edge. Flags select the mode; clientapp owns every mode's +// native media edge. Flags select the mode; app owns every mode's // lifecycle. package main @@ -13,11 +13,11 @@ import ( "os/signal" "syscall" - "github.com/TNTcraftHIM/Piik/internal/client/clientapp" + "github.com/TNTcraftHIM/Piik/internal/app" ) func main() { - var options clientapp.Options + var options app.Options flag.Func("site", "save and open a Piik Site origin", func(value string) error { options.Site = value options.SiteSet = true @@ -25,13 +25,13 @@ func main() { }) flag.BoolVar(&options.Local, "local", false, "use the self-contained Local room authority") flag.BoolVar(&options.Link, "link", false, "create one public Viewer invitation link") - flag.BoolVar(&options.Debug, "debug", false, "save opt-in Client diagnostics to rotated files") + flag.BoolVar(&options.Debug, "debug", false, "save opt-in App diagnostics to rotated files") flag.StringVar(&options.LogDir, "log-dir", "", "diagnostic directory (overrides PIIK_LOG_DIR)") flag.StringVar(&options.CaptureProcess, "capture-process", "", "path to the platform native capture process") flag.StringVar(&options.TunnelProcess, "tunnel-process", "", "path to the packaged public tunnel process") - flag.StringVar(&options.ConfigPath, "config", "", "path to the Client configuration file") + flag.StringVar(&options.ConfigPath, "config", "", "path to the App configuration file") flag.StringVar(&options.LANAddress, "lan-address", "", "LAN IPv4 address used in Local invitations") - flag.IntVar(&options.Port, "port", clientapp.DefaultLocalPort, "Local Piik server port") + flag.IntVar(&options.Port, "port", app.DefaultLocalPort, "Local Piik server port") flag.Parse() options.DisableBrowser = os.Getenv("PIIK_CLIENT_GATE_NO_BROWSER") == "true" @@ -45,7 +45,7 @@ func main() { } }() } - if err := clientapp.Run(ctx, options); err != nil { + if err := app.Run(ctx, options); err != nil { if options.DisableBrowser { fmt.Fprintln(os.Stderr, err) } diff --git a/cmd/piik-client/piik.ico b/cmd/piik-app/piik.ico similarity index 100% rename from cmd/piik-client/piik.ico rename to cmd/piik-app/piik.ico diff --git a/cmd/piik-client/piik_windows_amd64.syso b/cmd/piik-app/piik_windows_amd64.syso similarity index 100% rename from cmd/piik-client/piik_windows_amd64.syso rename to cmd/piik-app/piik_windows_amd64.syso diff --git a/docs/README.md b/docs/README.md index 5dbf74e..c012a17 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,7 +7,7 @@ | What you need | Start here | | --- | --- | | Join a friend or share a screen | [Quick Start](../README.md) | -| Run Client, choose a mode, or fix capture trouble | [Client guide](../cmd/piik-client/README.md) | +| Run App, choose a mode, or fix capture trouble | [App guide](../cmd/piik-app/README.md) | | Collect a useful bug report | [Diagnostics and export](./reference/configuration.md#diagnostics) | | Host your own site | [Self-hosting](./operations/self-hosting.md) | | Configure ports, access or persistence | [Configuration reference](./reference/configuration.md) | @@ -17,6 +17,9 @@ The public entry points have English and Chinese versions. Technical references keep one owner rather than duplicate the full documentation tree. +Contributors should follow the [naming convention](./reference/naming.md) for +display names, commands, packages and App/Server/Browser code boundaries. + ## Run from source Use Node from [.node-version](../.node-version), npm from diff --git a/docs/adr/0002-memory-resident-protected-rooms.md b/docs/adr/0002-memory-resident-protected-rooms.md index a85fffd..8e9e0f7 100644 --- a/docs/adr/0002-memory-resident-protected-rooms.md +++ b/docs/adr/0002-memory-resident-protected-rooms.md @@ -43,7 +43,7 @@ Hosted Server uses SQLite by default: directory; service/container templates select a writable persistent directory; - an explicit absolute path selects that SQLite file; - `ROOM_DATABASE_PATH=:memory:` explicitly selects process-only rooms, whose - authority ends at process exit. Client Local uses this memory composition + authority ends at process exit. App Local uses this memory composition directly and does not inherit Hosted environment defaults. Stable mode stores only `roomId`, Host-token digest, Viewer-grant digest, diff --git a/docs/adr/0006-fixed-high-native-sender-canary.md b/docs/adr/0006-fixed-high-native-sender-canary.md index b3e6dd0..692db03 100644 --- a/docs/adr/0006-fixed-high-native-sender-canary.md +++ b/docs/adr/0006-fixed-high-native-sender-canary.md @@ -14,7 +14,7 @@ current room, signaling, routing, audio, packaging, and Browser Viewer contract. ## Decision The fixed-HIGH native sender candidate is not a product surface and its private -wire remains deleted. The current native Client boundary is defined by +wire remains deleted. The current native App boundary is defined by [ADR-0010](./0010-cross-platform-client-runtime.md). The deleted one-Viewer loopback proved that a fixed 1280x720@30 source could diff --git a/docs/adr/0007-path-isolated-representation-quality.md b/docs/adr/0007-path-isolated-representation-quality.md index 5f9ec98..bb55ac2 100644 --- a/docs/adr/0007-path-isolated-representation-quality.md +++ b/docs/adr/0007-path-isolated-representation-quality.md @@ -77,7 +77,7 @@ it does not need a second bitrate, resolution, FPS, or layer-control system. from the exact sender and comparative delivery proof from the same Viewer over a real prepared candidate. It does not set bitrate, resolution, FPS, or layer, infer a physical bottleneck, or combine quality measurements into a score. A - native Client P2P edge obtains that category from Pion GCC: after real + native App P2P edge obtains that category from Pion GCC: after real transport feedback and encoded-frame progress, a target payload bitrate below the source's measured H.264 plus Opus payload is `bandwidth`; sufficient target payload is `none`; missing feedback or source progress is `unknown`. diff --git a/docs/adr/0008-window-scoped-audio-capture.md b/docs/adr/0008-window-scoped-audio-capture.md index 41d754c..b8f0fd1 100644 --- a/docs/adr/0008-window-scoped-audio-capture.md +++ b/docs/adr/0008-window-scoped-audio-capture.md @@ -1,6 +1,6 @@ # ADR-0008: Browser Screen-Audio Scope -- Status: accepted for Browser capture and the Windows Client audio paths +- Status: accepted for Browser capture and the Windows App audio paths - Date: 2026-08-21 - Last updated: 2026-08-27 @@ -13,7 +13,7 @@ application. Sharing a system mix can unintentionally include calls or notifications. Windows offers a narrower native primitive through WASAPI application loopback -for one selected process tree. The native Client owns that path for selected +for one selected process tree. The native App owns that path for selected windows; a selected display uses the default render-device loopback when the platform probe and physical gate report it. @@ -34,10 +34,10 @@ platform probe and physical gate report it. 5. Do not describe generic Browser system audio as application-isolated. UI and documentation must leave source scope to the Browser's actual result. 6. Windows process-tree audio for a selected window, and default render-device - loopback for a selected display, are Client capabilities when the platform - probe and physical gate pass. WGC/MF video and the Client media boundary are owned by + loopback for a selected display, are App capabilities when the platform + probe and physical gate pass. WGC/MF video and the App media boundary are owned by [ADR-0010](./0010-cross-platform-client-runtime.md); measurements are in - [Native Client media](../research/native-client-media.md). + [Native App media](../research/native-client-media.md). ## Consequences diff --git a/docs/adr/0009-optional-nat-prediction.md b/docs/adr/0009-optional-nat-prediction.md index e90c294..5f6ff42 100644 --- a/docs/adr/0009-optional-nat-prediction.md +++ b/docs/adr/0009-optional-nat-prediction.md @@ -1,12 +1,12 @@ # ADR-0009: Optional Connection-Local NAT Prediction -- Status: accepted as an optional Site and Client capability +- Status: accepted as an optional Site and App capability - Date: 2026-09-02 ## Context The self-hosted deployment has two auxiliary STUN-only listeners for controlled -NAT measurements, while a self-contained Client needs public discovery without +NAT measurements, while a self-contained App needs public discovery without depending on that deployment. A disposable namespace lab showed that a sequential, endpoint-dependent mapping can sometimes be reached when the remote peer receives a small set of adjacent server-reflexive candidates. The result is @@ -25,7 +25,7 @@ connection acquisition reuses the route controller's existing opportunity ledger defaults on, remains Host-controllable, locks while sharing, and is not persisted beyond that share generation. 2. An enabled Site derives ports 3479 and 3480 from its first ordinary STUN - authority on UDP 3478. Public-link Client mode instead supplies one ordinary + authority on UDP 3478. Public-link App mode instead supplies one ordinary public STUN destination and two fixed public survey destinations; pure LAN mode supplies none. The same share switch and ICE configuration cover every Browser or Native P2P edge. SFU PeerConnections remain unchanged. @@ -69,7 +69,7 @@ connection acquisition reuses the route controller's existing opportunity ledger Positive: -- Sites with their own listeners and self-contained public-link Clients can use +- Sites with their own listeners and self-contained public-link Apps can use the same bounded mechanism while pure Browser/LAN operation stays unchanged; - normal ICE remains immediately available, so an unavailable auxiliary STUN listener or unsuccessful prediction cannot delay direct or SFU fallback; diff --git a/docs/adr/0010-cross-platform-client-runtime.md b/docs/adr/0010-cross-platform-client-runtime.md index 0af41bb..a541a7d 100644 --- a/docs/adr/0010-cross-platform-client-runtime.md +++ b/docs/adr/0010-cross-platform-client-runtime.md @@ -1,4 +1,4 @@ -# ADR-0010: Cross-Platform Client Runtime +# ADR-0010: Cross-Platform App Runtime - Status: accepted capability-provider architecture and native endpoint media boundary - Date: 2026-09-05 @@ -26,8 +26,8 @@ Hosted and Local deployments diverge without improving the media path. Room authority and local media capability are independent choices. A room may come from Local, a temporary public link, or a configured Site while each -participant independently uses Browser media or available Client capability. -Binding these choices into exclusive Client modes prevents mixed Browser/Native +participant independently uses Browser media or available App capability. +Binding these choices into exclusive App modes prevents mixed Browser/Native topologies and makes a saved Site unavailable while another room source runs. ## Decision @@ -37,7 +37,7 @@ topologies and makes a saved Site unavailable while another room source runs. core and the same built Browser assets with local configuration; no deployment gets a second product core. Its implementation is owned by [ADR-0012](./0012-shared-go-backend-core.md). -2. The packaged product is Piik Client. Its Go process is the cross-platform +2. The packaged product is Piik App. Its Go process is the cross-platform entry and native capability provider. It starts `/health` and one `/control` endpoint on IPv4 loopback within ports `39721` through `39730` before room- source selection and retains them until the process exits. @@ -49,7 +49,7 @@ topologies and makes a saved Site unavailable while another room source runs. 4. Loopback v9 starts with a strict `hello` handshake. Up to two participant control sessions may coexist; each retains its own share and media lifetime. This bounds concurrent Native work, not the shared server's room count. - Ending one control session cannot end another; Client exit waits for all + Ending one control session cannot end another; App exit waits for all owned sessions to retire. Health discovery reports only separately probed native capture booleans. Native Viewer receive/NAT remains available when capture or hardware encode is absent. An active control session may @@ -68,20 +68,20 @@ topologies and makes a saved Site unavailable while another room source runs. wrapper or UI. 6. The system Browser remains the UI. Browser extensions, userscripts, Electron, Tauri, and resident services need new evidence before they can replace this - smaller boundary. A Client-opened Site stores a non-secret opt-in at that + smaller boundary. An App-opened Site stores a non-secret opt-in at that exact Browser origin, so later manually opened pages may discover the running - Client. Pages without that opt-in do not probe localhost or request local- + App. Pages without that opt-in do not probe localhost or request local- network permission. Clearing Site data simply requires opening it from the - Client again. + App again. 7. A self-contained Local deployment serves reachable LAN peers without a central Piik service. Its explicit `--link` mode starts one accountless - Cloudflare Quick Tunnel for the same HTTP/WebSocket surface. The Client + Cloudflare Quick Tunnel for the same HTTP/WebSocket surface. The App reserves the exact IPv4 listener before creating that tunnel, then applies its HTTPS origin before the server starts serving that listener. It retains the same memory RoomStore, Browser UI, Viewer grant, signaling, and route controller. The Host sends the ordinary invitation link and the Viewer needs only a Browser. Cloudflare terminates this temporary control path; WebRTC media stays - P2P and uses public STUN. The link ends with the Client and is not a persistent + P2P and uses public STUN. The link ends with the App and is not a persistent Site, SFU, or TURN fallback. 8. Browser and Native are local media adapters beneath the same authenticated participant, connection identity, copy capacity, and committed route graph. @@ -108,10 +108,10 @@ topologies and makes a saved Site unavailable while another room source runs. edge supplies Host preview and the existing Browser LiveKit publisher. It neither consumes route-copy capacity nor starts port mapping; an assigned SFU publication still consumes its existing route copy. Native code does not - implement LiveKit or another representation policy. The Client discovers + implement LiveKit or another representation policy. The App discovers packaged capture capability at startup. Its Host page offers the Browser's - standard picker and each exact Client-owned screen/window; the user must select one - and the Client never guesses a target. The same room quality settings select + standard picker and each exact App-owned screen/window; the user must select one + and the App never guesses a target. The same room quality settings select native capture size, frame rate, video/audio bitrate, and the platform encoder's quality-versus-speed hint. A live quality or source change prepares a replacement capture/encoder generation and swaps it behind the existing @@ -125,11 +125,11 @@ topologies and makes a saved Site unavailable while another room source runs. stock Browser sender from the stable local bridge; existing evidence alone decides commit or rollback, and a later operation may return to Native. No extra threshold, timer, score, route operation, or representation ladder is - added. Only a consumed Client-launch marker travels in the URL fragment. + added. Only a consumed App-launch marker travels in the URL fragment. Exact target identity travels over loopback. -9. The Client uses the system Browser as its only UI. On every launch, the current +9. The App uses the system Browser as its only UI. On every launch, the current lightweight control center offers Local, public link, and Site. The Site value - is stored in Client configuration and remains one click on later launches; + is stored in App configuration and remains one click on later launches; selecting Local or public link does not disable background RPC access for the saved Site. Command-line mode selectors remain automation inputs rather than the normal interface. An @@ -142,28 +142,28 @@ topologies and makes a saved Site unavailable while another room source runs. and two bounded public survey destinations. Site mode consumes that Site's configured STUN survey. Both feed the same connection-local prediction adapter; Native additionally owns its UDP socket and best-effort port mapping. -11. One Client configuration owns the optional Site origin and an optional, +11. One App configuration owns the optional Site origin and an optional, user-chosen Local access password. A blank value leaves the Local site open; a value gates that site through the existing SiteAccess authority. The - Client bootstraps a selected page through a fragment consumed before - authentication; the page retains only the non-secret Client opt-in at its - origin. Friends use the existing room invitation grant. No Client-specific + App bootstraps a selected page through a fragment consumed before + authentication; the page retains only the non-secret App opt-in at its + origin. Friends use the existing room invitation grant. No App-specific room authorization system is added. 12. Local authority shutdown first ends every in-memory room through the current - `room-closed` path, then closes signaling and HTTP. The Client cancels the + `room-closed` path, then closes signaling and HTTP. The App cancels the server context, calls that end-then-close sequence under one bounded timeout, and only then closes the public tunnel and the loopback service. It does not restart a vanished authority. -13. Client assembly consumes the immutable application release from the same full +13. App assembly consumes the immutable application release from the same full Git revision and an explicit supported target. The Go binary embeds that release's built Browser assets and the package `REVISION` records the same revision; a revision mismatch fails rather than loading a stale private - contract. Client-scoped pull requests build every + contract. App-scoped pull requests build every target and must start the assembled Local authority, pass `/healthz`, and stop it cleanly before the candidate is accepted. 14. The root package manifest is the single dependency contract for the Browser bundle and repository tooling. No host installs packages to run Piik, so - the manifest has no runtime half, and no second Client dependency list or + the manifest has no runtime half, and no second App dependency list or post-install package surgery is used. ## Consequences @@ -188,12 +188,12 @@ received 30+ H.264 RTP packets over a selected direct A Windows Browser gate also receives process-loopback Opus on both native edges. A separate remote gate proves that `--link` generates the ordinary public invitation and carries the unchanged Viewer page and -WebSocket control path, then disappears when the Client exits. An isolated +WebSocket control path, then disappears when the App exits. An isolated LiveKit gate also proves native capture through the loopback Browser bridge and the existing SFU publisher, including a live 1080p-to-480p profile change and complete cleanup. A Browser-Host-to-Native-Viewer gate additionally proves that the Viewer claims -the v8 Client control session and Chrome decodes the 1280x720 source; the encoded +the v8 App control session and Chrome decodes the 1280x720 source; the encoded downstream edge has a separate H.264/Opus RTP integration gate. One-link Browser media and physical non-Windows capture remain separate gates. GitHub runners compile all three platform adapters. The macOS arm64 sidecar also @@ -210,7 +210,7 @@ the existing route controller. Unknown feedback and stopped-source windows stay ineligible. The local trust boundary is intentionally per-user: the instance token identifies -the running Client but is not authentication against another local process. +the running App but is not authentication against another local process. A physical home-router gate created and removed a UPnP mapping for an ephemeral UDP listener. The integrated native Host gate still passed capture, two-edge @@ -232,4 +232,4 @@ architectural claim. - [LocalSend protocol](https://github.com/localsend/protocol/blob/main/README.md) - [Sunshine local Web UI](https://docs.lizardbyte.dev/projects/sunshine/latest/) - [Syncthing local GUI/API](https://docs.syncthing.net/users/config.html) -- [Native Client media evidence](../research/native-client-media.md) +- [Native App media evidence](../research/native-client-media.md) diff --git a/docs/adr/0011-browser-assisted-native-fanout.md b/docs/adr/0011-browser-assisted-native-fanout.md index b5b63e2..ff5de5e 100644 --- a/docs/adr/0011-browser-assisted-native-fanout.md +++ b/docs/adr/0011-browser-assisted-native-fanout.md @@ -15,7 +15,7 @@ share one encoder. The later [Chromium legacy probe](../research/advanced-peer-distribution.md#chromium-legacy-fanout-probe) demonstrates a non-standard clean-path exception, with unresolved feedback and -statistics. It is not an accepted replacement for this Browser/Client boundary. +statistics. It is not an accepted replacement for this Browser/App boundary. The repository already has the required Native boundary: a Pion receiver can accept H.264/Opus RTP and its encoded source can feed bounded downstream Pion @@ -24,7 +24,7 @@ UI and capture owner. ## Decision -1. A Client-launched Browser Host whose current codec is H.264 and whose +1. An App-launched Browser Host whose current codec is H.264 and whose topology optimization is enabled uses one local Browser-to-Native ingress. The existing `HostPeer` owns its sender, clone, quality settings and pause; the existing Native receiver owns encoded fanout. VP8 and disabled quality @@ -38,7 +38,7 @@ UI and capture owner. Browser sender candidate for one degraded edge; that candidate is an exception when sharing an encoding cannot sustain that path. Savings never justify worse delivery or disabling native Browser quality adaptation. -4. If the Client is absent or the local ingress fails, the Host keeps the +4. If the App is absent or the local ingress fails, the Host keeps the Browser capture and recreates affected senders on their current assigned routes. Capture and room authority survive loss of the optional fanout. Ordinary Browser pages retain their existing media path. @@ -49,7 +49,7 @@ UI and capture owner. ## Consequences -- A Client-launched Browser Host can use one Browser encode plus Native encoded +- An App-launched Browser Host can use one Browser encode plus Native encoded fanout while preserving the existing UI and room behavior. - A pure Browser relay remains framework-owned and may encode per child because the standard Browser API has no cross-connection encoded-frame injection @@ -62,7 +62,7 @@ UI and capture owner. children; failure retains Browser capture through ordinary sender recovery. - A Windows/Chrome two-child gate proves one local encode, 1080p at about 30 fps on both Viewers, live quality changes, pause/resume, source audio changes, and - Client-exit recovery. Weak-path automatic adaptation and its cost remain + App-exit recovery. Weak-path automatic adaptation and its cost remain physical acceptance, not a consequence of the clean-path result. ## References diff --git a/docs/adr/0012-shared-go-backend-core.md b/docs/adr/0012-shared-go-backend-core.md index bc64483..0bb496e 100644 --- a/docs/adr/0012-shared-go-backend-core.md +++ b/docs/adr/0012-shared-go-backend-core.md @@ -7,15 +7,15 @@ One TypeScript/Node server owned HTTP, room authority, admission, signaling, and routing. Hosted and Local composed the same application from it, and the packaged -Client supervised it as a Node child beside a pinned runtime and an extracted +App supervised it as a Node child beside a pinned runtime and an extracted application tree. [ADR-0010](./0010-cross-platform-client-runtime.md) accepted that shape because a second implementation of rooms, signaling, or routing would make the two deployments diverge without improving the media path. -That boundary is paid for in every deployment. The Client package carries a +That boundary is paid for in every deployment. The App package carries a language runtime and an installed dependency tree beside its Go entry, a production host needs Node and npm to install and validate a release, and one -user entry runs two processes whose lifetime a supervisor owns. The Client +user entry runs two processes whose lifetime a supervisor owns. The App already owns a Go process, Pion media, and its capture sidecars, so the second runtime buys only the existing server code. @@ -26,11 +26,11 @@ the same Browser build. ## Decision 1. One Go module at the repository root owns the product core. - `cmd/piik-server` (Hosted) and `cmd/piik-client` (Client) are entry + `cmd/piik-server` (Hosted) and `cmd/piik-app` (App) are entry points over the same `internal/server` packages and own only their defaults, reachability, and lifecycle policy. Neither reimplements rooms, admission, signaling, or routing. The TypeScript server, its bundled runtime, the process - supervisor, and the Client's runtime/application selection flags are deleted in + supervisor, and the App's runtime/application selection flags are deleted in the same boundary. 2. The Browser UI stays React/TypeScript. Node, npm, Vite, vitest, and `tsx` remain build and gate tooling and stop being a runtime requirement on any @@ -65,19 +65,19 @@ the same Browser build. [ADR-0002](./0002-memory-resident-protected-rooms.md). Both storage modes, their validation, and their failure policy are unchanged, and no build requires a C toolchain. -8. The port changed no contract. Signaling stayed on its then-current v21 wire; the Client +8. The port changed no contract. Signaling stayed on its then-current v21 wire; the App loopback stays v8, capture framing stays v4, and the HTTP API, cookies, error codes, and close codes keep their exact shapes. No compatibility alias, dual reader, or migration is added for a change of implementation language. ## Consequences -- The Client is one process. Room authority, the loopback capability service, and +- The App is one process. Room authority, the loopback capability service, and native media share it, so a panic in the server ends the Local session exactly as a crashed Node child did, and the capability service no longer survives a failed room authority. Hosted exits non-zero and systemd restarts it; nothing restarts a vanished authority in place. -- Package and runtime cost falls in three places: the Client package loses its +- Package and runtime cost falls in three places: the App package loses its bundled runtime and dependency tree, the application release becomes the server binary with its notices and revision, and a production host installs no packages during a release. One Windows 11 before/after run measured cold start diff --git a/docs/deployment.md b/docs/deployment.md index 1c8ecf1..cf15788 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -45,36 +45,36 @@ extracts its own artifact to verify it. The archive contains exactly `piik-server`, `LICENSE`, `THIRD-PARTY-NOTICES.txt`, and `REVISION`. Upload the archive, manifest, and descriptor together to `/opt/piik/uploads`. -The same application descriptor is also the Client assembly input. On each +The same application descriptor is also the App assembly input. On each target platform, provide that platform's Go toolchain: ```sh PIIK_GO=/path/to/go node scripts/assemble-client.mjs \ /outside/repository/app-release/piik-.release.json \ - /outside/repository/Piik-Client \ + /outside/repository/piik-app \ --target windows-amd64 \ --capture /path/to/platform-capture \ --tunnel /path/to/cloudflared ``` Assembly refuses a dirty or different revision and emits one directory with the -Client executable, the Browser assets taken from that release and embedded in +App executable, the Browser assets taken from that release and embedded in it, the selected sidecars, notices, and matching `REVISION`. Its required target is one of `windows-amd64`, `linux-amd64`, or `darwin-arm64`; every supplied binary input must match it. It does not create an installer, auto-updater, release tag, or compatibility bundle. -Darwin Client assembly runs on macOS with its SDK and cgo enabled: the pinned +Darwin App assembly runs on macOS with its SDK and cgo enabled: the pinned LiveKit dependency's [Darwin CPU statistics](https://github.com/mackerelio/go-osstat/blob/v0.2.8/cpu/cpu_darwin_cgo.go) call Mach APIs. Windows and Linux -Client builds keep cgo disabled. A core check on those hosts explicitly skips +App builds keep cgo disabled. A core check on those hosts explicitly skips the Darwin binaries; macOS build and package verification belong to the existing native runner. This does not change the cgo-free linux/amd64 Server artifact. The platform package also carries its native presentation metadata: Windows embeds the icon in the Go executable, Linux emits a freedesktop desktop entry under `share/`, and macOS emits a thin `.app` launcher with an ICNS resource. -The latter two are packaging metadata only and do not duplicate the Client +The latter two are packaging metadata only and do not duplicate the App executable. CI and local release-candidate builds use the same wrapper on the target's @@ -88,7 +88,7 @@ node scripts/package-client-candidate.mjs \ ``` The wrapper downloads the pinned public-link sidecar, verifies its digest, -builds the target Client and available capture process, executes every packaged +builds the target App and available capture process, executes every packaged runtime, and emits one `tar.gz` plus its SHA-256 file. Retain the descriptor and successful deployment output as release metadata. Do @@ -97,7 +97,7 @@ or hashes. After `validate` succeeds on an explicit workflow dispatch with `client_checks=true`, CI packages the Server application release and the -three-platform Client candidates that consume it. The artifacts are retained +three-platform App candidates that consume it. The artifacts are retained for 14 days. Ordinary `main` pushes do not run these packaging jobs. This workflow does not create a tag, public GitHub Release, or deployment. @@ -107,13 +107,13 @@ install. ## Update Check -The application, Server deployment, and platform Client all use the full Git +The application, Server deployment, and platform App all use the full Git revision as their release identity. A formal GitHub Release must use that exact 40-character revision as its tag and keep the corresponding release URL. The current CI workflow produces short-lived candidates but does not publish a GitHub Release; publication remains an explicit distribution decision. -The default Client launcher starts immediately, then performs one background +The default App launcher starts immediately, then performs one background request to the official Piik GitHub Releases API. It shows a link only when the latest release has a valid full revision different from the packaged one. The request sends no current revision, credentials, room data, or media data; @@ -137,7 +137,7 @@ state. A different current-revision file may be supplied as its only argument. ## Permanent-Room Schema Cutover -The schema 2 / signaling v23 cutover required matching Web/Client/Server builds +The schema 2 / signaling v23 cutover required matching Web/App/Server builds and an accepted active-session interruption. Native control stayed v9; that schema change preserved Browser credential keys. It was not an app-only release. The separate [brand cutover](./research/piik-rename-plan.md) must preserve this @@ -177,7 +177,7 @@ and [backup guidance](https://www.sqlite.org/backup.html) define this offline op The first move from external services to embedded STUN/SFU is a coordinated infrastructure and protocol transaction, including Node-to-Go where still needed. Complete the [self-hosting cutover procedure](./operations/self-hosting.md#coordinated-embedded-media-cutover) -with matching Web/Server signaling and native protocol v9 Client builds, +with matching Web/Server signaling and native protocol v9 App builds, accepted active-session interruption, released UDP ports, and exact unit/environment/proxy/service recovery. The routine wrapper does not perform that transaction; it requires an already running packaged Go release and cannot diff --git a/docs/design/piik-brand.html b/docs/design/piik-brand.html index c1b8876..d7f10e2 100644 --- a/docs/design/piik-brand.html +++ b/docs/design/piik-brand.html @@ -164,7 +164,7 @@
03 / Hang out

A little room for your people.人到齐，就一起看。

-
Display / 显示名称 PiikTechnical / 技术名称 piik-clientWebsite / 官网 piik.tvPage title / 页签 Piik | 6020 · 📺
+
Display / 显示名称 PiikTechnical / 技术名称 piik-appWebsite / 官网 piik.tvPage title / 页签 Piik | 6020 · 📺
Design study · 09 Sep 2026 · 待讨论，尚未替换产品Layout references: LocalSend · RustDesk