0 Fork 0

Files

T

AAA 9150e9d312 feat(app): improve startup, diagnostics and direct connections (#397 )

## Problem and outcome / 问题与结果

Machines with several local addresses could fail before opening Piik, and startup or connection failures were difficult to diagnose. This phase adds Local invitation-address selection and accessible diagnostics, preserves useful startup errors, and repairs media preparation and recovery without changing room authority or routing policy. It also aligns language handling, playback, public downloads and contributor documentation with the resulting behavior.

## Release notes

### 中文

- **多网卡也能正常选择启动方式。** 本地房间在需要时显示网卡名称与局域网地址，供你选择朋友所在的网络；公网邀请和连接已有站点不再因多个局域网地址而无法启动。
- **更容易排查启动和连接问题。** 启动页新增“诊断启动”，同时记录 App 与网页诊断；网页版也有独立诊断入口。启动失败会显示具体原因和重试方法，Windows 双击启动后的错误会停留等待确认。诊断模式下异常退出会保存报告，ZIP 由用户自行保留或清理。
- **减少连接准备中的无谓等待。** 普通候选发现不再等待可选端口映射；修正连接重启时旧候选与完成通知的处理，以及部分准备失败后的反馈。Native 媒体连接可在网络支持时使用 IPv6 直连，同时保留 IPv4 路径。
- **修正分享恢复中的状态问题。** 切换画面后重新计算首播保护所需的新帧；SFU 恢复时应用最新画质设置；一次应答发送失败不再使整个会话失去 Native 接收能力。密码错误提示也进行了去重。
- **改善播放与全屏交互。** 同步 Safari 原生全屏中的播放、音量与退出状态；可操作的视频画面显示手形光标。
- **统一语言匹配并完善翻译贡献。** 简体、繁体中文系统均默认显示简体中文，其余系统默认英文；保留中英文与纯视觉模式快捷切换，提供中英文社区翻译教程和额外语言接入方式。
- **整理下载与官网说明。** Release 附件集中展示三个平台的 App ZIP 和 Server 程序包，源码版本与校验值收进更新说明的折叠区。官网保留内嵌短片，并提供独立观看链接；教程、下载文案和运维指南同步更新。

**升级：** App 请完整解压对应平台的 ZIP 并保留目录结构。服务端按部署指南升级，保留现有配置与 SQLite 数据。此次更新不改变现有通信协议和存储格式。

**测试范围：** 主要验证 Windows App 与桌面浏览器。macOS、Linux 实机采集和移动端、跨公网 IPv6 的更广泛验证仍待完成，欢迎试用反馈。

### English

- **Choose how to start on machines with multiple network addresses.** Local rooms show interface names and invitation addresses when a choice is needed. Public invitations and connections to an existing Site no longer fail because several LAN addresses are available.
- **Diagnose startup and connection problems more easily.** The launcher now offers Debug launch for both App and browser diagnostics, alongside a separate browser diagnostics control. Startup failures include their cause and retry guidance; Windows errors remain visible for confirmation after a double-click launch. Failed exits in diagnostic mode save a report. Exported ZIPs remain available until you move or delete them.
- **Remove unnecessary connection setup waits.** Ordinary candidate discovery no longer waits for optional gateway mapping. Fixes cover stale candidates and completion signals during ICE restarts, and feedback from failed connection preparation. Native media can use direct IPv6 connections where available while retaining IPv4 paths.
- **Keep sharing recovery aligned with the current source and settings.** Source changes count new frames for startup protection, SFU recovery uses the latest quality preferences, and one failed answer submission no longer disables Native receiving for the entire session. Duplicate password-error feedback has also been removed.
- **Improve playback and fullscreen interaction.** Safari native fullscreen now synchronizes playback, volume and exit state. Interactive video surfaces show a pointer cursor.
- **Align language selection and community translation guidance.** Simplified and Traditional Chinese system locales select Simplified Chinese; other systems default to English. Chinese, English and visual-mode shortcuts remain, with bilingual translation guides and a registration path for additional languages.
- **Simplify release downloads and refresh the website.** Release attachments contain the three App ZIPs and the Server runtime archive; source identity and checksums appear in a collapsed section of the release notes. The website keeps its embedded introduction and adds a standalone viewing link, with updated setup, download and operations guidance.

**Upgrading:** Extract the complete App ZIP for your platform and keep its directory structure. Follow the deployment guide for Server upgrades, preserving existing configuration and SQLite data. Existing wire contracts and storage formats are unchanged.

**Test coverage:** Windows App and desktop browsers are the primary validated paths. Physical macOS/Linux capture, broader mobile coverage and IPv6 across separate public networks remain open; testing and feedback are welcome.

## Verification / 验证

- `npm run check`: PASS, including TypeScript, 807 tests in 60 files and the production Web build.
- `npm run check:client`: PASS on Windows, including Go formatting/tests/vet, Windows/Linux core builds and native Windows capture compile/probe. Darwin requires the native macOS CI runner.
- `npm run gate:client-media`: PASS with Chrome 152 and a real captured test window on Windows. Two receivers obtained video and audio; live and paused profile changes, recovery frames and cleanup passed. This is a single-machine test, not a public-NAT success-rate measurement.
- `npm run gate:client-link`: PASS using the newly packaged Windows App. A separate remote machine fetched its temporary public page and completed the WebSocket upgrade; App exit closed the link and cleanup passed.
- Server runtime and Windows App candidate packaging: PASS, including archive identity/checksums and execution from the extracted App ZIP. Native Linux/macOS package checks still run in the publishing pipeline before publication.
- `node scripts/check-docs.mjs`, `scripts/check-project-state.ps1`, `git diff --check` and `npm run build:website`: PASS. Seven documentation-size gardening advisories and the existing Vite chunk-size advisory remain non-blocking.
- Browser review: English/Chinese website setup and direct-download links, narrow layout and diagnostics/language controls checked. Native popover accessibility correctly exposes expanded/collapsed state without a duplicate attribute owner.
- Independent audit found no P0/P1/P2 issues; focused race checks for portmapping and mediaedge passed. Diagnostic archive accumulation is retained by the owner's explicit choice. The currently unreachable language menu placement issue is a first-community-language prerequisite in TODO.

Physical macOS/Linux capture, broader mobile behavior, restricted-network/endurance coverage and cross-network Native IPv6 remain explicitly outside this candidate's evidence.

## Impact / 影响

Compatible feature release, planned as v1.2.0 from v1.1.2. Browser/server v23, Native control v9, capture v7 and SQLite schema 2 remain unchanged. No new telemetry service, retry policy or configuration requirement is introduced. Public Demo remains open-entry and P2P-only. NAT-PMP dependency corrections are explicitly deferred to the next release and are not claimed here.

The existing product, configuration, translation, research and operations owners were updated. Raw audits, handoffs, diagnostic logs and experimental sources are excluded from the PR.

2026-09-13 18:32:24 +08:00

9.9 KiB

Raw Blame History

Help translate Piik

中文 · Contributing

Piik currently includes Simplified Chinese and English. You can improve a label, proofread a guide, or contribute another language. Translations are reviewed through GitHub issues and pull requests.

For a wording suggestion, open an issue with the language, page or control, current text, proposed text and a brief reason. A screenshot or the steps to reach the text help establish context. Remove private invitations, passwords and personal content from screenshots. A wording suggestion does not require a development environment.

Make your first correction

Try the affected screen and read the nearby controls. Check both existing languages when helpful; the terminology and voice guide owns names and writing style.
Fork Piik and work on a branch from current main, following Contributing. Small text edits can also be proposed through GitHub's file editor.
Find the text in the files below. In a locale file, change the string value after the colon. Keep the key and its placeholders. Search the key in the source to see where it appears; for example:
```
rg -n -F 'host.title' src/client
```
Preview the affected screen and run the relevant checks. For a typo in one language, edit that language. If the underlying meaning changes, update the corresponding messages in every registered language.
Open a PR to main. Explain the wording problem, the language and surfaces changed, and what you checked. Mention anything you could not preview; maintainers can help with technical validation. PR format and publication follow Contributing.

Find the right text

Surface	Editable source
App launcher and shared Browser/App UI, including tooltips and accessible labels	English, Chinese
Welcome lines and changing browser-tab titles	`welcome.*` messages and the title-frame catalog at the end of those same files
Website	Page markup and interactive labels; text is paired by `en` and `zh-CN`
Introduction film	Film sources; captions, artwork and playback labels have their own bilingual text
App console window	`consoleCopy` in console.go; entries are ordered English, Chinese, visual; retain the third slot even when empty
README and entry guides	README pair, getting started and self-hosting, each with a `.zh-CN.md` counterpart

The App and Server serve the same web UI. Edit source files; build output and release packages are generated. Translating an App message does not also translate a website caption. Update related instructions when an action name changes. Technical references keep one shared version; see documentation ownership.

Preserve meaning and syntax

Write naturally for the target audience. Use the shared glossary for role and password names. Introductions may be light; actions, errors and deployment steps must be clear. Preserve the conditions on performance, platform and connection claims. A cultural reference should still make sense to someone unfamiliar with it. Machine-assisted drafts need proofreading by someone who understands the language and the screen; raise unclear source text in the PR instead of guessing.

Locale files are TypeScript objects. These are existing examples:

// en.ts
"host.title": "{name}'s screen",
// zh.ts
"host.title": "{name} 的屏幕",

host.title is the lookup key; {name} is supplied by the application. Move the placeholder to fit the sentence, preserving its spelling, braces and number of occurrences. The current formatter substitutes each supplied variable once; repeating {name} would leave the second occurrence visible. It accepts plain strings, not HTML or ICU plural expressions. If a language needs plural forms or different sentence composition, describe the actual case so the caller and formatter can be changed together.

Keep quotes, escapes and commas valid. Preserve commands, config keys, URLs, download filenames and format markers such as %s in Go console text. Translate link labels and image descriptions; repair internal anchors when translating Markdown headings. Keep legal license text and third-party notices intact.

Add a language

Search existing issues and PRs for the language first. For a larger translation, start an issue with its language tag, intended coverage and any terminology or layout questions, so contributors can coordinate work and review.

Copy src/client/locales/en.ts to a file such as fr.ts. Translate the messages and title frames, rename the two exports, and retain the Record<CopyKey, string> and TitleFrameCatalog types imported from zh.ts. Chinese currently defines the key set; either existing language can provide context. Complete all keys rather than spreading an English catalog over missing translations.
Import the exports in locales/index.ts and add one registry entry. For example, after translating the two exports:
```
fr: { name: "Français", short: "FR", tag: "fr", copy: fr, titleFrames: frTitleFrames },
```
Use an ASCII locale filename/key, the language's own name in name, a compact button label in short, and a matching language tag in tag. Keep the short label recognizable in one to three characters, such as 中, EN or FR; distinguish regional/script variants when they coexist. The registry supplies the language controls, document language, saved selection and App launch handoff. Chinese, English and visual mode retain their direct buttons; additional languages share one dropdown slot after visual mode. The selected extra language's short label appears on that slot, with its full name in the menu. Initial selection matches a registered tag or key, then its base language; unregistered languages use English. A saved choice takes precedence. The shared system-language policy also covers Chinese script and region variants across App, Server UI and website.
Check complete screens and the launch flow. New UI languages use English in the App console until its own translation is added. Console additions also require updating the launcher and loopback accepted-language checks together; use the App module map.
State coverage in the PR. Website, film and documentation translations can be contributed separately; their existing language controls must be updated when adding a language there. For right-to-left scripts, include text direction and layout verification; a translated catalog alone does not establish RTL support.

Pure-visual mode is an optional presentation, not another language to translate. The small visual scenes are shared with text modes; translate their labels and explanations in the normal catalog. Keep the visual option available.

Preview and check

Use the Node/npm versions and local setup in Run from source. For UI catalog edits, run from the repository root:

npm ci
npm run typecheck
npm test -- tests/copy.test.ts

Type checking catches missing keys. The copy tests check registered catalogs for empty text and mismatched placeholders, plus language selection and handoff. Tests do not judge translation quality.

Run the local UI and server as described in the source guide. Choose the language from the top-right controls, open the affected screen and inspect long names or counts in context. Check narrow windows, keyboard focus, tooltips and accessible labels. With extra languages registered, verify that the dropdown stays usable near viewport edges and exposes its expanded/collapsed state to assistive technology. For new languages, also check a reload, App launch, switching back to English, and the optional visual mode. Keep meaningful phrases together instead of adding spaces or hard line breaks to force one desktop layout.

Website and film changes use the website preview. For Markdown changes, run node scripts/check-docs.mjs after staging new files, then review GitHub's rendered Markdown and translated links. Additional checks for code changes follow Contributing.

9.9 KiB Raw Blame History