[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75V5JSYX3ZD5PTFZQACBW3Q":3,"skill-same:01M75V5JSYX3ZD5PTFZQACBW3Q":82},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M75V5JSYX3ZD5PTFZQACBW3Q","platform",null,"Maps Puck's OS seams (Puck.Platform, .Windows, .Linux): native windows, Win32\u002FWayland\u002FXCB, displays and VRR, precision waits, memory, clipboard, camera and desktop capture, probes, HID transports.","ByteTerrace\u002FPuck","ByteTerrace","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F18753984?v=4","01M75V2WCB9PGGC3H7RZC7AXPS","01M75V2WD0NJPRNP5HJ75VZGD0",2,"Apache-2.0","https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplatform\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: platform\ndescription: \"Maps Puck's OS seams (Puck.Platform, .Windows, .Linux): native windows, Win32\u002FWayland\u002FXCB, displays and VRR, precision waits, memory, clipboard, camera and desktop capture, probes, HID transports.\"\n---\n\n# Platform\n\nA map of where Puck meets the operating system. Three projects, one shape:\n\n- **`Puck.Platform`** holds the OS-neutral contracts and the pieces that need\n  no OS code: window, clipboard, camera, image-capture and audio-render\n  contracts, camera discovery polling, the unmanaged allocator, probe\n  readings and kernel sockets, null fallbacks and the declining recording\n  factories.\n- **`Puck.Platform.Windows`** implements them over Win32, Media Foundation,\n  Windows Graphics Capture, WASAPI, Raw Input, HID, XInput and GameInput.\n- **`Puck.Platform.Linux`** implements windows over Wayland and XCB and\n  registers null or declining services for everything else.\n\nA composition root picks one platform per seam with one\n`OperatingSystem.IsWindows()` branch (`WorldBootComposition`, and\n`WindowsPresentationRegistration` or `LinuxPresentationRegistration` in the\n`Puck.Launcher.Windows` and `.Linux` projects). The project READMEs\n([neutral](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform\u002FREADME.md),\n[Windows](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform.Windows\u002FREADME.md),\n[Linux](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform.Linux\u002FREADME.md)) are the developer\nreference. When this file and the code disagree, the code wins and this file is\ncorrected in the same change.\n\n## Find the owner by what you need\n\n| You need | Owner | Read |\n|---|---|---|\n| A native window, its events and its surface | `INativeWindow`, `INativeWindowFactory`, `INativeWindowBackend`; `Win32NativeWindow`, `WaylandNativeWindow`, `XcbNativeWindow`; `ConfiguredNativeWindow` as the headless stand-in | [neutral README](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform\u002FREADME.md#what-lives-here) |\n| Which display kind to open on Linux | `NativeDisplayEnvironment`, `NativeDisplayKindSelector` (environment variables only) | [neutral README](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform\u002FREADME.md#what-lives-here) |\n| Variable refresh range, display timing, colour space, keeping the display awake | `IDisplayTimingInfo` on `Win32NativeWindow` (`Win32NativeWindow.Vrr.cs`), `EdidVariableRefreshParser`, `Win32DisplayColorSpaceProbe`, the display power request in `Win32NativeWindow.DisplayPower.cs` | [host pacing](..\u002F..\u002F..\u002Fdocs\u002Freference\u002Fhosting.md#host-pacing) |\n| Wait until a deadline without spinning or raising timer resolution | `IPrecisionWaiter`: `Win32HighResolutionWaitableTimer` (the window implements it; `Win32PrecisionWaiter` serves a headless host through `AddWindowsPrecisionWaiter`), consumed by `LauncherHostLoop.WaitUntil` | [below](#play-nice-with-the-host) |\n| Unmanaged memory | `IAllocator`, `MimallocAllocator`, registered by `AddPuckAllocator` | [neutral README](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform\u002FREADME.md#what-lives-here) |\n| Clipboard | `IClipboardService`: `Win32ClipboardService`; `NullClipboardService` on Linux | [neutral README](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform\u002FREADME.md#what-lives-here) |\n| Mouse, keyboard and pointer lock at the OS boundary | `Win32NativeWindow` messages, `Win32RawInput` (relative motion per mouse), `Win32PointerLock`, `WindowInputQueue` | [pointer input](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform.Windows\u002FREADME.md#pointer-input) |\n| Pads and HID devices at the transport | `WindowsInputTransports.CreateGamepadManager` over `Win32HidDeviceSource` and `Win32XboxAcquisitionSource` (XInput, GameInput) | `input` |\n| Device lights | `ILampArrayDevice`: `Win32LampArrayDevice` | [abstractions](..\u002F..\u002F..\u002Fdocs\u002Freference\u002Fabstractions.md) |\n| A webcam's frames, CPU pixels or shared GPU textures | `ICameraCaptureService` (`EnumerateDevices`, `TryOpenPixels`, `TryOpenShared`) → `ICameraGraph`; `Win32MediaFoundationCameraService`, `Win32CameraGraph`'s MTA worker, `Win32D3D11CameraFrameConverter`; discovery polling in `CameraDeviceScanner` | [camera capture](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform.Windows\u002FREADME.md#camera-capture) |\n| A desktop or another window's pixels as a feed | `INativeImageCaptureService`: `Win32NativeImageCaptureService`, `Win32GraphicsCaptureFeed` | [Windows README](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform.Windows\u002FREADME.md#contents) |\n| A passthrough screen that forwards input to a desktop window | `Win32DesktopPassthrough`, `Win32PassthroughWindow` | [device input](..\u002F..\u002F..\u002Fdocs\u002Freference\u002Finput.md) |\n| A probe: a kernel over camera, strobe or rendered frames | `ProbeReading`, `ProbeReadingRing`, `IProbeKernelHost`, `ProbeKernelRequest`; `Win32ProbeKernelBench`, `Win32RenderedProbeKernelHost`; `ProbeTrackPlayer` replays recorded readings | [neutral README](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform\u002FREADME.md#what-lives-here) |\n| The audio output device | `IAudioRenderDeviceFactory`: `WasapiAudioRenderDeviceFactory`; none on Linux | `media` |\n| Video encoders, loopback and microphone capture | `IVideoEncoderFactory`, `IAudioCaptureSourceFactory`: `MediaFoundationVideoEncoderFactory`, `WasapiAudioCaptureSourceFactory`; declining factories on Linux | `media` |\n\n## Registration shape\n\n- `PlatformWindowingServiceRegistration.AddPlatformWindowing` registers only\n  the neutral pieces (display probe, platform support, window factory). Each\n  platform package adds one method per seam:\n  `WindowsPlatformServiceRegistration.AddWindowsPlatformWindowing`,\n  `AddWindowsCameraCapture`, `AddWindowsRecordingPlatform`,\n  `AddWindowsAudioRender`, `AddWindowsPrecisionWaiter`, and the Linux\n  equivalents on `LinuxPlatformServiceRegistration`\n  (`AddLinuxPlatformWindowing`, `AddLinuxCameraCapture`, which registers the\n  null camera and image-capture services today, `AddLinuxRecordingPlatform`).\n  A new backend implements the contract in its platform project and replaces\n  the null service in that platform's registration method.\n- A method that constructs a `[SupportedOSPlatform(\"windows\")]` type carries\n  the attribute itself, so CA1416 makes the caller guard with\n  `OperatingSystem.IsWindows()`. The guard lives in the composition root,\n  never inside a platform project.\n- `Puck.Platform.Windows` stays `net11.0`, like `Puck.Platform`, so the\n  annotations keep firing. `WindowsCaptureProjection.targets` re-declares the\n  WinRT projection at every entry point that references it, on Windows hosts.\n- A seam with no backend registers a null or declining service that answers\n  with a reason (`NullCameraCaptureService`, `DecliningVideoEncoderFactory`),\n  never a missing service a caller must guess about.\n\n## Play nice with the host\n\nAGENTS.md's ruling applies here first: Puck uses the host's threads, waits,\ntimers and virtual memory, and never spins in place of a wait or raises\nprocess-wide timer resolution. In this area that means:\n\n- Wait on `IPrecisionWaiter`. `Win32HighResolutionWaitableTimer` uses\n  `CREATE_WAITABLE_TIMER_HIGH_RESOLUTION`, which wakes within about half a\n  millisecond without `timeBeginPeriod` and without spinning;\n  `LauncherHostLoop.WaitUntil` re-reads its clock after each wait and falls\n  back to a one-millisecond sleep where no waiter exists. A busy loop on a\n  stopwatch is a defect, however short.\n- Swap-chain waits pace a windowed host ([host pacing](..\u002F..\u002F..\u002Fdocs\u002Freference\u002Fhosting.md#host-pacing));\n  the timer only bounds what the swap chain cannot.\n- Camera graphs own their native objects on one MTA worker thread, joined with\n  a bound on disposal; camera scans run at most one at a time on a worker and\n  hand back completed snapshots without blocking the caller.\n- The window holds a display-required power request while open, because a\n  powered-off display stops the compositor retiring presents.\n\n## Contracts that bite\n\n- **An empty camera list means no cameras.** `EnumerateDevices` returns empty\n  only when the machine has none; a failed scan throws\n  `InvalidOperationException`, so a caller never reads a failed scan as every\n  camera unplugged.\n- **A successful open is usable.** A pixel open has already published a frame\n  from every stream; a shared open has validated native GPU input. A shared\n  ring's consumer acquires a slot until its GPU submission retires, and the\n  camera drops a frame rather than overwrite a texture still being sampled.\n- **Relative mouse motion is never integrated into a cursor estimate.** Raw\n  Input supplies per-mouse deltas; the system cursor supplies positions and\n  buttons.\n- **An agent's World opens no physical device.** `--devices none` drops every\n  OS event before a seat; never inject real input to test\n  ([puck-world](..\u002Fpuck-world\u002FSKILL.md#an-agents-world-opens-no-physical-device)).\n- **A device or OS protocol is independent work.** Consult several\n  independent sources (vendor documentation, kernel drivers, other open\n  implementations), cite each and note where they disagree (AGENTS.md).\n\n## Where each contract is enforced\n\n| Contract | Enforced by |\n|---|---|\n| Windows-only code runs only behind an OS guard | CA1416 over `[SupportedOSPlatform]` on the registration methods |\n| `Puck.Platform.Linux`'s closure has no Windows dependency | the `Puck.Platform.Linux` lane profile in `build\u002FArchitecture.props` (`puck architecture`) |\n| A failed camera scan is distinct from an empty one | `ICameraCaptureService.EnumerateDevices` throwing; `CameraDeviceScanner` keeping failures apart from empty lists |\n| One waiter per timer, no spinning | `Win32HighResolutionWaitableTimer` (one waiter at a time, re-armed per wait) |\n\n## Open gaps\n\n- **Linux has no camera, desktop-capture, audio-render, video-encoder,\n  audio-capture or clipboard backend**, and its windows hold no display\n  request (Wayland's idle inhibit, X11's screensaver suspend). Windowed\n  Wayland and XCB behaviour has not been run on real Linux hardware.\n- **Duplicates recorded in the refactoring packet:** camera plane validation\n  and L8\u002FBGRA packing (`Win32FaceAuthenticationCameraGraph.cs` beside\n  `CameraFramePacking`), and the latest-value seqlock (`ProbeReadingRing`\n  beside `Puck.Hosting`'s `PublishBuffer\u003CT>`)\n  ([refactoring campaign](..\u002F..\u002F..\u002Fdocs\u002Fplans\u002Fopen-items.md#refactoring-campaign)).\n- A reading taken while the compositor is not composing still looks like a\n  slow frame ([open items](..\u002F..\u002F..\u002Fdocs\u002Fplans\u002Fopen-items.md)).\n\n## Verify\n\n- Build what you touched: `dotnet build src\u002FPuck.Platform.Windows -c Release`\n  or `src\u002FPuck.Platform.Linux`; a Linux change also gets the WSL2 build the\n  [Linux launcher README](..\u002F..\u002F..\u002Fsrc\u002FPuck.Launcher.Linux\u002FREADME.md) gives,\n  and says what it does not prove.\n- Laws: `tests\u002FPuck.Platform.Windows.Tests` (camera enumeration and pixel\n  delivery skip on a machine with no colour camera), and the host-loop laws in\n  `tests\u002FPuck.Launcher.Tests` (`OffscreenBoundaryLawTests` drives a manual\n  `IPrecisionWaiter`).\n- A window, a display, a camera or pointer lock is a windowed World, a GPU leg\n  (`verification`); hand it back as a verification request unless your brief\n  grants it.\n\n## Look-alikes\n\n- Host pacing decisions (swap chain, timer grid, catch-up bursts) belong to\n  `Puck.Launcher` and the hosting reference; this area only supplies the waits\n  and display facts they read.\n- `Puck.Input` turns transports into `InputSignal`s and binds them (`input`);\n  this area only acquires devices and window events.\n- Camera capture feeds screens and probes; `capture.*` records the game\n  (`media`).\n\n## Route adjacent work\n\n| Skill | Route there for |\n|---|---|\n| `input` | Gamepads, HID protocols, haptics, `InputArbiter`, window input mapping and bindings. |\n| `media` | The audio device's mixer and director, recording sessions, encoders as the recording graph uses them. |\n| `rendering` | Swap chains, presenters, the frame pacer, shared GPU textures a camera ring feeds, the camera conversion shader. |\n| `puck-world` | Screens that show a camera or desktop feed, probes rows, booting a windowed World. |\n| `dotnet-performance` | Allocation and interop cost on a platform hot path. |\n| `verification` | GPU legs for windowed checks, the private CLI copy. |\n","# Platform\n\nA map of where Puck meets the operating system. Three projects, one shape:\n\n- **`Puck.Platform`** holds the OS-neutral contracts and the pieces that need\n  no OS code: window, clipboard, camera, image-capture and audio-render\n  contracts, camera discovery polling, the unmanaged allocator, probe\n  readings and kernel sockets, null fallbacks and the declining recording\n  factories.\n- **`Puck.Platform.Windows`** implements them over Win32, Media Foundation,\n  Windows Graphics Capture, WASAPI, Raw Input, HID, XInput and GameInput.\n- **`Puck.Platform.Linux`** implements windows over Wayland and XCB and\n  registers null or declining services for everything else.\n\nA composition root picks one platform per seam with one\n`OperatingSystem.IsWindows()` branch (`WorldBootComposition`, and\n`WindowsPresentationRegistration` or `LinuxPresentationRegistration` in the\n`Puck.Launcher.Windows` and `.Linux` projects). The project READMEs\n([neutral](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform\u002FREADME.md),\n[Windows](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform.Windows\u002FREADME.md),\n[Linux](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform.Linux\u002FREADME.md)) are the developer\nreference. When this file and the code disagree, the code wins and this file is\ncorrected in the same change.\n\n## Find the owner by what you need\n\n| You need | Owner | Read |\n|---|---|---|\n| A native window, its events and its surface | `INativeWindow`, `INativeWindowFactory`, `INativeWindowBackend`; `Win32NativeWindow`, `WaylandNativeWindow`, `XcbNativeWindow`; `ConfiguredNativeWindow` as the headless stand-in | [neutral README](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform\u002FREADME.md#what-lives-here) |\n| Which display kind to open on Linux | `NativeDisplayEnvironment`, `NativeDisplayKindSelector` (environment variables only) | [neutral README](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform\u002FREADME.md#what-lives-here) |\n| Variable refresh range, display timing, colour space, keeping the display awake | `IDisplayTimingInfo` on `Win32NativeWindow` (`Win32NativeWindow.Vrr.cs`), `EdidVariableRefreshParser`, `Win32DisplayColorSpaceProbe`, the display power request in `Win32NativeWindow.DisplayPower.cs` | [host pacing](..\u002F..\u002F..\u002Fdocs\u002Freference\u002Fhosting.md#host-pacing) |\n| Wait until a deadline without spinning or raising timer resolution | `IPrecisionWaiter`: `Win32HighResolutionWaitableTimer` (the window implements it; `Win32PrecisionWaiter` serves a headless host through `AddWindowsPrecisionWaiter`), consumed by `LauncherHostLoop.WaitUntil` | [below](#play-nice-with-the-host) |\n| Unmanaged memory | `IAllocator`, `MimallocAllocator`, registered by `AddPuckAllocator` | [neutral README](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform\u002FREADME.md#what-lives-here) |\n| Clipboard | `IClipboardService`: `Win32ClipboardService`; `NullClipboardService` on Linux | [neutral README](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform\u002FREADME.md#what-lives-here) |\n| Mouse, keyboard and pointer lock at the OS boundary | `Win32NativeWindow` messages, `Win32RawInput` (relative motion per mouse), `Win32PointerLock`, `WindowInputQueue` | [pointer input](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform.Windows\u002FREADME.md#pointer-input) |\n| Pads and HID devices at the transport | `WindowsInputTransports.CreateGamepadManager` over `Win32HidDeviceSource` and `Win32XboxAcquisitionSource` (XInput, GameInput) | `input` |\n| Device lights | `ILampArrayDevice`: `Win32LampArrayDevice` | [abstractions](..\u002F..\u002F..\u002Fdocs\u002Freference\u002Fabstractions.md) |\n| A webcam's frames, CPU pixels or shared GPU textures | `ICameraCaptureService` (`EnumerateDevices`, `TryOpenPixels`, `TryOpenShared`) → `ICameraGraph`; `Win32MediaFoundationCameraService`, `Win32CameraGraph`'s MTA worker, `Win32D3D11CameraFrameConverter`; discovery polling in `CameraDeviceScanner` | [camera capture](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform.Windows\u002FREADME.md#camera-capture) |\n| A desktop or another window's pixels as a feed | `INativeImageCaptureService`: `Win32NativeImageCaptureService`, `Win32GraphicsCaptureFeed` | [Windows README](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform.Windows\u002FREADME.md#contents) |\n| A passthrough screen that forwards input to a desktop window | `Win32DesktopPassthrough`, `Win32PassthroughWindow` | [device input](..\u002F..\u002F..\u002Fdocs\u002Freference\u002Finput.md) |\n| A probe: a kernel over camera, strobe or rendered frames | `ProbeReading`, `ProbeReadingRing`, `IProbeKernelHost`, `ProbeKernelRequest`; `Win32ProbeKernelBench`, `Win32RenderedProbeKernelHost`; `ProbeTrackPlayer` replays recorded readings | [neutral README](..\u002F..\u002F..\u002Fsrc\u002FPuck.Platform\u002FREADME.md#what-lives-here) |\n| The audio output device | `IAudioRenderDeviceFactory`: `WasapiAudioRenderDeviceFactory`; none on Linux | `media` |\n| Video encoders, loopback and microphone capture | `IVideoEncoderFactory`, `IAudioCaptureSourceFactory`: `MediaFoundationVideoEncoderFactory`, `WasapiAudioCaptureSourceFactory`; declining factories on Linux | `media` |\n\n## Registration shape\n\n- `PlatformWindowingServiceRegistration.AddPlatformWindowing` registers only\n  the neutral pieces (display probe, platform support, window factory). Each\n  platform package adds one method per seam:\n  `WindowsPlatformServiceRegistration.AddWindowsPlatformWindowing`,\n  `AddWindowsCameraCapture`, `AddWindowsRecordingPlatform`,\n  `AddWindowsAudioRender`, `AddWindowsPrecisionWaiter`, and the Linux\n  equivalents on `LinuxPlatformServiceRegistration`\n  (`AddLinuxPlatformWindowing`, `AddLinuxCameraCapture`, which registers the\n  null camera and image-capture services today, `AddLinuxRecordingPlatform`).\n  A new backend implements the contract in its platform project and replaces\n  the null service in that platform's registration method.\n- A method that constructs a `[SupportedOSPlatform(\"windows\")]` type carries\n  the attribute itself, so CA1416 makes the caller guard with\n  `OperatingSystem.IsWindows()`. The guard lives in the composition root,\n  never inside a platform project.\n- `Puck.Platform.Windows` stays `net11.0`, like `Puck.Platform`, so the\n  annotations keep firing. `WindowsCaptureProjection.targets` re-declares the\n  WinRT projection at every entry point that references it, on Windows hosts.\n- A seam with no backend registers a null or declining service that answers\n  with a reason (`NullCameraCaptureService`, `DecliningVideoEncoderFactory`),\n  never a missing service a caller must guess about.\n\n## Play nice with the host\n\nAGENTS.md's ruling applies here first: Puck uses the host's threads, waits,\ntimers and virtual memory, and never spins in place of a wait or raises\nprocess-wide timer resolution. In this area that means:\n\n- Wait on `IPrecisionWaiter`. `Win32HighResolutionWaitableTimer` uses\n  `CREATE_WAITABLE_TIMER_HIGH_RESOLUTION`, which wakes within about half a\n  millisecond without `timeBeginPeriod` and without spinning;\n  `LauncherHostLoop.WaitUntil` re-reads its clock after each wait and falls\n  back to a one-millisecond sleep where no waiter exists. A busy loop on a\n  stopwatch is a defect, however short.\n- Swap-chain waits pace a windowed host ([host pacing](..\u002F..\u002F..\u002Fdocs\u002Freference\u002Fhosting.md#host-pacing));\n  the timer only bounds what the swap chain cannot.\n- Camera graphs own their native objects on one MTA worker thread, joined with\n  a bound on disposal; camera scans run at most one at a time on a worker and\n  hand back completed snapshots without blocking the caller.\n- The window holds a display-required power request while open, because a\n  powered-off display stops the compositor retiring presents.\n\n## Contracts that bite\n\n- **An empty camera list means no cameras.** `EnumerateDevices` returns empty\n  only when the machine has none; a failed scan throws\n  `InvalidOperationException`, so a caller never reads a failed scan as every\n  camera unplugged.\n- **A successful open is usable.** A pixel open has already published a frame\n  from every stream; a shared open has validated native GPU input. A shared\n  ring's consumer acquires a slot until its GPU submission retires, and the\n  camera drops a frame rather than overwrite a texture still being sampled.\n- **Relative mouse motion is never integrated into a cursor estimate.** Raw\n  Input supplies per-mouse deltas; the system cursor supplies positions and\n  buttons.\n- **An agent's World opens no physical device.** `--devices none` drops every\n  OS event before a seat; never inject real input to test\n  ([puck-world](..\u002Fpuck-world\u002FSKILL.md#an-agents-world-opens-no-physical-device)).\n- **A device or OS protocol is independent work.** Consult several\n  independent sources (vendor documentation, kernel drivers, other open\n  implementations), cite each and note where they disagree (AGENTS.md).\n\n## Where each contract is enforced\n\n| Contract | Enforced by |\n|---|---|\n| Windows-only code runs only behind an OS guard | CA1416 over `[SupportedOSPlatform]` on the registration methods |\n| `Puck.Platform.Linux`'s closure has no Windows dependency | the `Puck.Platform.Linux` lane profile in `build\u002FArchitecture.props` (`puck architecture`) |\n| A failed camera scan is distinct from an empty one | `ICameraCaptureService.EnumerateDevices` throwing; `CameraDeviceScanner` keeping failures apart from empty lists |\n| One waiter per timer, no spinning | `Win32HighResolutionWaitableTimer` (one waiter at a time, re-armed per wait) |\n\n## Open gaps\n\n- **Linux has no camera, desktop-capture, audio-render, video-encoder,\n  audio-capture or clipboard backend**, and its windows hold no display\n  request (Wayland's idle inhibit, X11's screensaver suspend). Windowed\n  Wayland and XCB behaviour has not been run on real Linux hardware.\n- **Duplicates recorded in the refactoring packet:** camera plane validation\n  and L8\u002FBGRA packing (`Win32FaceAuthenticationCameraGraph.cs` beside\n  `CameraFramePacking`), and the latest-value seqlock (`ProbeReadingRing`\n  beside `Puck.Hosting`'s `PublishBuffer\u003CT>`)\n  ([refactoring campaign](..\u002F..\u002F..\u002Fdocs\u002Fplans\u002Fopen-items.md#refactoring-campaign)).\n- A reading taken while the compositor is not composing still looks like a\n  slow frame ([open items](..\u002F..\u002F..\u002Fdocs\u002Fplans\u002Fopen-items.md)).\n\n## Verify\n\n- Build what you touched: `dotnet build src\u002FPuck.Platform.Windows -c Release`\n  or `src\u002FPuck.Platform.Linux`; a Linux change also gets the WSL2 build the\n  [Linux launcher README](..\u002F..\u002F..\u002Fsrc\u002FPuck.Launcher.Linux\u002FREADME.md) gives,\n  and says what it does not prove.\n- Laws: `tests\u002FPuck.Platform.Windows.Tests` (camera enumeration and pixel\n  delivery skip on a machine with no colour camera), and the host-loop laws in\n  `tests\u002FPuck.Launcher.Tests` (`OffscreenBoundaryLawTests` drives a manual\n  `IPrecisionWaiter`).\n- A window, a display, a camera or pointer lock is a windowed World, a GPU leg\n  (`verification`); hand it back as a verification request unless your brief\n  grants it.\n\n## Look-alikes\n\n- Host pacing decisions (swap chain, timer grid, catch-up bursts) belong to\n  `Puck.Launcher` and the hosting reference; this area only supplies the waits\n  and display facts they read.\n- `Puck.Input` turns transports into `InputSignal`s and binds them (`input`);\n  this area only acquires devices and window events.\n- Camera capture feeds screens and probes; `capture.*` records the game\n  (`media`).\n\n## Route adjacent work\n\n| Skill | Route there for |\n|---|---|\n| `input` | Gamepads, HID protocols, haptics, `InputArbiter`, window input mapping and bindings. |\n| `media` | The audio device's mixer and director, recording sessions, encoders as the recording graph uses them. |\n| `rendering` | Swap chains, presenters, the frame pacer, shared GPU textures a camera ring feeds, the camera conversion shader. |\n| `puck-world` | Screens that show a camera or desktop feed, probes rows, booting a windowed World. |\n| `dotnet-performance` | Allocation and interop cost on a platform hot path. |\n| `verification` | GPU legs for windowed checks, the private CLI copy. |\n",{"name":5,"description":7},"main","2ef814b84c9595144e052c6dcd300badb619ee2f",".claude\u002Fskills\u002Fplatform",0,"https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck","https:\u002F\u002Fgithub.com\u002FByteTerrace","https:\u002F\u002Fbyteterrace.com","2026-11-12 13:59:16",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add ByteTerrace\u002FPuck --skill platform",{"tool":37,"command":38},"bunx","bunx skills add ByteTerrace\u002FPuck --skill platform",{"tool":40,"command":41},"pnpm","pnpm dlx skills add ByteTerrace\u002FPuck --skill platform","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplatform\u002FSKILL.md",true,[45,51,55,59,63,67,71,75,78],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"evals\u002Fpl01-precise-wait\u002Fgraders\u002Fhigh-resolution-timer.md","REFERENCE","参考文档",841,"https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplatform\u002Fevals\u002Fpl01-precise-wait\u002Fgraders\u002Fhigh-resolution-timer.md",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"evals\u002Fpl01-precise-wait\u002Fgraders\u002Fnames-the-waiter.md",118,"https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplatform\u002Fevals\u002Fpl01-precise-wait\u002Fgraders\u002Fnames-the-waiter.md",{"path":56,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":57,"sourceHtmlUrl":58},"evals\u002Fpl01-precise-wait\u002Fgraders\u002Fskill-fired.md",36,"https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplatform\u002Fevals\u002Fpl01-precise-wait\u002Fgraders\u002Fskill-fired.md",{"path":60,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":61,"sourceHtmlUrl":62},"evals\u002Fpl01-precise-wait\u002Fprompt.md",790,"https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplatform\u002Fevals\u002Fpl01-precise-wait\u002Fprompt.md",{"path":64,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":65,"sourceHtmlUrl":66},"evals\u002Fpl02-linux-camera-backend\u002Fgraders\u002Ffailed-scan-throws.md",662,"https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplatform\u002Fevals\u002Fpl02-linux-camera-backend\u002Fgraders\u002Ffailed-scan-throws.md",{"path":68,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":69,"sourceHtmlUrl":70},"evals\u002Fpl02-linux-camera-backend\u002Fgraders\u002Flinux-registration.md",102,"https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplatform\u002Fevals\u002Fpl02-linux-camera-backend\u002Fgraders\u002Flinux-registration.md",{"path":72,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":73,"sourceHtmlUrl":74},"evals\u002Fpl02-linux-camera-backend\u002Fgraders\u002Fos-choice-in-composition-root.md",940,"https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplatform\u002Fevals\u002Fpl02-linux-camera-backend\u002Fgraders\u002Fos-choice-in-composition-root.md",{"path":76,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":57,"sourceHtmlUrl":77},"evals\u002Fpl02-linux-camera-backend\u002Fgraders\u002Fskill-fired.md","https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplatform\u002Fevals\u002Fpl02-linux-camera-backend\u002Fgraders\u002Fskill-fired.md",{"path":79,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":80,"sourceHtmlUrl":81},"evals\u002Fpl02-linux-camera-backend\u002Fprompt.md",796,"https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplatform\u002Fevals\u002Fpl02-linux-camera-backend\u002Fprompt.md",[83,90,97,104,111,118],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":18},"01M75V6X1GBYDMSMJC8VXXPFAP","verification","Verifies Puck changes: landing bar, builds, stale DLLs, flaky tests, GPU\u002Fheavy leases, coverage, source-scan or regex laws versus type\u002Fcompiler enforcement, and writing tests.","https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fverification\u002FSKILL.md",[],[],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":18},"01M75V6TM3F9A7ZMA0Q43RVJSF","tooling","Maps shared build\u002FCLI architecture, compiler assembly identity, candidate installation, generated sections, and host admission.","https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Ftooling\u002FSKILL.md",[],[],{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":103,"publishedAt":18},"01M75V6R4E6AY73X27MC6EE5X5","tooling-files","Maps shared repository tooling for files, paths, Git queries, project ownership and Markdown fences. Load before adding or changing a helper in these areas.","https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Ftooling-files\u002FSKILL.md",[],[],{"skillNo":105,"name":106,"nameZh":6,"description":107,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":18},"01M75V6N2P9XWWPH7EHRKMBTEC","symbol-analysis","Answers C# structure questions with puck references and declarations: which types derive from, implement or override a symbol, who references it, safe to delete or rename. Text: content-search.","https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsymbol-analysis\u002FSKILL.md",[],[],{"skillNo":112,"name":113,"nameZh":6,"description":114,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":115,"categories":116,"keywords":117,"publishedAt":18},"01M75V6HRKM57BD8Q7A4N8QN0C","state","Maps Puck's state and rule engine (Puck.State, .Rules, .Search, .Topology, .Vectors, .Generators): arena, journal scopes, undo, hashing, rule compiler, faults, transforms, search, draws.","https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fstate\u002FSKILL.md",[],[],{"skillNo":119,"name":120,"nameZh":6,"description":121,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":122,"categories":123,"keywords":124,"publishedAt":18},"01M75V6CE3X73KNZYFRT9A5W8F","sdf-authoring","Authors creations: shape rows, primitives, blends, folds, palettes, paints, render lanes, rigs, bake work and bytes, creation stats. Use to sculpt or fix a part. Grammar: puck-dsl; GPU: rendering.","https:\u002F\u002Fgithub.com\u002FByteTerrace\u002FPuck\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsdf-authoring\u002FSKILL.md",[],[]]