Files
Piik/docs/verification-status.md
T
AAA d76e94eb71 feat(app): improve capture controls and sharing feedback
## Problem and outcome / 问题与结果

Windows App users can now choose whether to show the capture border. The same border owner handles source previews and active capture; unsupported or denied requests keep normal capture available. The source picker distinguishes an absent/incompatible App, unavailable capture capability, failed enumeration and a genuinely empty list. Chrome's pending local-access permission no longer holds optional Viewer reception.

This phase also reduces tooltip obstruction and contains a failed Linux encoder output within its own branch. Browser/server v23, Native control v9 and capture v7 remain compatible. Closes #401.

## Release notes

### 中文

这是一次分享体验更新,重点改进 Windows 采集边框、App 选源反馈和提示浮窗,并修复 Linux 采集输出的故障隔离。

- **采集边框可选。** Windows App 选源器新增「显示采集边框」,位于声音开关左侧,默认关闭。支持的系统上,来源预览也会隐藏边框。
- **找不到窗口时,提示更明确。** 区分 App 未连接、版本不兼容、采集不可用和读取失败;授权后可以刷新列表重试。改善 Chrome 首次访问时的观看连接,避免本机授权等待拖慢入座。
- **提示浮窗更顺手。** 统一 500 毫秒悬停延迟,减少对画面和控件的遮挡,改善触屏长按和关闭操作;只用于说明的控件使用普通鼠标光标。
- **Linux 分享更稳。** 修复单路编码输出失败可能连带中断其他输出的问题。
- **排查文档更完整。** 补充 App 来源列表、Windows 10 黄框及浏览器 WebRTC 设置的排查说明。

使用新的采集边框开关,请更新 Windows App 并刷新已打开的网页。Windows 10 没有对应的系统接口,边框仍由系统显示;文档中心提供可选处理方法。系统权限或其他采集会话也可能要求保留边框。

### English

This sharing update improves Windows capture borders, App source selection and tooltips, and fixes failure isolation between Linux capture outputs.

- **Choose whether to show the capture border.** The Windows App source picker adds a **Show capture border** switch to the left of audio, off by default. Source previews also hide the border on supported systems.
- **Clearer source-selection feedback.** The picker distinguishes an unavailable or incompatible App, unsupported capture and a failed source list. Refresh after granting access to retry. Pending local-access permission in Chrome no longer delays Browser reception for Viewers.
- **Less intrusive tooltips.** A consistent 500 ms hover delay, improved placement and touch-hold behavior make guidance easier to read and dismiss. Help-only controls use the ordinary cursor.
- **More resilient Linux sharing.** A failed encoder output no longer interrupts healthy sibling outputs.
- **More useful troubleshooting.** The documentation covers App source lists, Windows 10 capture borders and browser WebRTC settings.

Update the Windows App and refresh open pages to use the capture-border switch. Windows 10 lacks the corresponding system API and retains its system border; an optional procedure is available in the documentation center. System permission or another capture session may also require the border to remain visible.

## Verification / 验证

- `npm run check`: TypeScript, 998 tests and production Web build passed.
- `npm run check:go`: Go formatting/tests/vet/target builds and Windows native capture checks passed. macOS cgo builds require their native CI runner.
- Documentation, repository hygiene and website build passed.
- Real Chrome 152 profiles: first-use local permission, recovery after consent and source-list refresh; optional Viewer discovery before/after consent; App Local without cross-address-space consent.
- Public invitation gate: link creation, remote page and WebSocket access, App exit and link retirement passed.
- Windows 11 border on/off, source preview and concurrent-capture checks have physical evidence. Tooltip hover, keyboard, touch-hold, dismissal and narrow-layout checks passed.
- [Candidate CI](https://github.com/TNTcraftHIM/Piik/actions/runs/35157993032) passed at `1d159831`: Server/container, Windows/Linux/macOS packages, Go race checks and frontend validation. Publication was skipped.
- Local Windows ZIP passed packaged startup, capture probing, embedded Web, helper identity/notices and clean-shutdown checks.
- Windows H.264 and VP8 Host gates passed live/paused settings, background recovery, source replacement, source-end/restart, decoded Viewer frames and complete resource cleanup.
- Final `0b370e6a` differs from the CI candidate only in TODO/status closure. Full Web/Go/native checks and website build passed again. The access/privacy gate passed credential-leak and cleanup checks.

## Impact / 影响

Compatible feature update for **v1.5.0**. No wire or storage version change. Older Apps retain their existing capture behavior through capability negotiation. Publication and matching deployments follow the release workflow.

The independent Windows x86 experiment is excluded. Physical 32-bit Windows, macOS/Linux capture, unsupported Windows border control, and actual border-permission denial remain outside this candidate's acceptance evidence. The original missing-window, public-link timeout and URL-handler crash reports still need affected-machine diagnostics.
2026-09-17 08:29:15 +08:00

7.0 KiB

Verification Status

Last updated: 2026-09-17

This file owns physical evidence limits that change how the product may be described. Status owns the execution/deployment index. Product modules own behavior; research owns measurements; Git owns completed implementation and obsolete package history.

Current Evidence

Windows App and Browser are the owner's primary acceptance targets. Current Go packages embed their Web assets and do not run a Node backend. The current contract is Browser/server v23, Native control v9 and capture v7.

Bounded current checks cover:

  • Native H264/VP8 output, compatible encoding reuse, different weak-budget grouping, keyframe-safe retarget and independent retirement;
  • Windows live/paused/quiet-source settings, source replacement and subsequent sharing, including media-object continuity where required;
  • Native H264 SFU video and decoded Opus through a profile change and closure;
  • Browser-to-App fanout and App-exit fallback;
  • concurrent Native sessions with independent media and retirement;
  • complete large encoded access-unit transport and bounded queue/cache behavior;
  • Linux container startup as non-root with a read-only filesystem, memory/SQLite restart semantics, diagnostics export, STUN and listener lifecycle; and
  • public embedded-SFU H264/VP8, audio, live profile changes and closure after the coordinated production cutover.

The owner confirmed Windows 10 whole-display capture resolved. Chromium WebRTC/IP-handling policy explains the verified local-media failure; it is a Browser policy limitation, not a Vivaldi-specific transport workaround.

The Windows capture-border control and borderless previews have physical Windows 11 evidence. Unsupported Windows and actual border-permission denial remain device checks. The optional Windows 10 Windhawk procedure is documented from its author and has not been tested with Piik on Windows 10.

NAT traversal and Auto codec selection are implemented features, not unfinished functionality. On 2026-09-09 the owner confirmed that the new NAT traversal is useful in actual use. That field confirmation is accepted; it does not claim a population success percentage or identify which candidate won without a trace. Neither a statistical NAT campaign nor exhaustive Auto hardware benchmarking is required to close this phase. Investigate further only from a new failure or a measured improvement worth its implementation and maintenance cost.

Candidate Evidence Boundary

The 2026-09-11 functional test acceptance used two genuine Windows App packages and matching Server source/Web builds under the same private contract. Both App/Site version directions delivered decoded 1080p H264 from an isolated native test window. Replacing the Server process preserved SQLite Host authority, private code-entry policy, Viewer grant/password authorization and App configuration. Already-open Host/Viewer pages reauthenticated without reloading and completed subsequent sharing. Exact measured identity belongs to the package descriptors and local structured acceptance result; Git retains the preparation history.

This is bounded single-machine Windows evidence. The local Server executables were built for Windows from the matching source; this run did not execute the Linux release archives. Process replacement used a forced stop on Windows and does not promise uninterrupted media. It does not cover game/audio endurance, storage faults or the wider device/network matrix.

The first public release passed real Server/three-platform App packaging and GitHub/Gitee publication, including anonymous mirror checksum verification. These packaging checks do not establish physical macOS/Linux capture or expand the device/network evidence below. Status owns current publication and activation state.

Remaining Device And Network Acceptance

The following are broader coverage and endurance tasks, not automatically new implementation mechanisms:

  • heterogeneous public-network P2P and multi-hop Browser/Native/SFU-fed relays;
  • Native IPv6 direct connections across separate networks with usable IPv6; local dual-stack checks establish socket and candidate behavior only;
  • Host/Viewer TUN/VPN combinations, migration and all-UDP-blocked bounded failure;
  • two-room public SFU load, real-game audio/video synchronization and sustained packet loss/recovery;
  • weaker Hosts at 720p30, 1080p30 and 1080p60, CPU/GPU contention, thermals, long-running resources and the 20-Viewer bound; and
  • physical mobile autoplay, background/lock, page reclamation, rotation, Wi-Fi/cellular migration and relay survival.

A short 20-Viewer topology run from an earlier revision proves only its tested invariants; it is not current-contract endurance or a public-network quality guarantee. A direct postflight with both endpoints on one machine proves public signaling and local media, not restricted-NAT traversal.

macOS/Linux physical capture/audio/recovery remains explicitly deferred by the owner. Linux producer compilation and older Mac SDK/package evidence do not prove the current Windows multi-output adaptation contract on those platforms.

Adaptation Boundaries

The encoder-pool research retains both successful and unsuccessful observations:

  • A prolonged shaped-network run recovered original output about 1.5 seconds after release and stayed near 30 fps; an earlier twelve-second observation missed recovery. The cause of that difference is not established.
  • H264's stock QP adaptation can take tens of seconds to restore full size.
  • Extreme single-core VP8 overload produced multi-second encode gaps that reset the stock CPU detector's samples. That result does not establish normal-device or Browser parity and does not authorize custom CPU thresholds.
  • Equal effective demands can share; incompatible demands may need more encoders. Extra fallback outputs, buffers and recovery keyframes have real costs.
  • The 360-to-187 encode-call result compares a bounded prototype with independent encoders. It is not an old-versus-new Native product CPU benchmark.

The earlier borrowed-child Browser experiment failed independent quality and accounting. The independent producer in ADR-0014 now has bounded H264/VP8 direct/relay, weak-path, lifecycle and A/V evidence on the acceptance candidate; its research owns results and limits. The owner authorized its release on 2026-09-09. Browser relay shares local outputs among its direct children; it still re-encodes received media. Native/SFU healthy forwarding remains encoded.

Interpretation

Configuration/unit/loopback checks prove their named invariants. Physical results belong to the tested revision, device and workload. Missing counters remain unknown. A new diagnostic collector must be checked in a real exported report, including retention and failed-collector information; logging a method call alone does not establish useful evidence. Browser/OS suspension remains a physical limit rather than a keepalive guarantee.