ByteTerrace/Puck / .claude/skills/platform
platform
VerifiedMaps Puck's OS seams (Puck.Platform, .Windows, .Linux): native windows, Win32/Wayland/XCB, displays and VRR, precision waits, memory, clipboard, camera and desktop capture, probes, HID transports.
Platform
A map of where Puck meets the operating system. Three projects, one shape:
Puck.Platformholds the OS-neutral contracts and the pieces that need no OS code: window, clipboard, camera, image-capture and audio-render contracts, camera discovery polling, the unmanaged allocator, probe readings and kernel sockets, null fallbacks and the declining recording factories.Puck.Platform.Windowsimplements them over Win32, Media Foundation, Windows Graphics Capture, WASAPI, Raw Input, HID, XInput and GameInput.Puck.Platform.Linuximplements windows over Wayland and XCB and registers null or declining services for everything else.
A composition root picks one platform per seam with one
OperatingSystem.IsWindows() branch (WorldBootComposition, and
WindowsPresentationRegistration or LinuxPresentationRegistration in the
Puck.Launcher.Windows and .Linux projects). The project READMEs
(neutral,
Windows,
Linux) are the developer
reference. When this file and the code disagree, the code wins and this file is
corrected in the same change.
Find the owner by what you need
| You need | Owner | Read |
|---|---|---|
| A native window, its events and its surface | INativeWindow, INativeWindowFactory, INativeWindowBackend; Win32NativeWindow, WaylandNativeWindow, XcbNativeWindow; ConfiguredNativeWindow as the headless stand-in | neutral README |
| Which display kind to open on Linux | NativeDisplayEnvironment, NativeDisplayKindSelector (environment variables only) | neutral README |
| 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 |
| 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 |
| Unmanaged memory | IAllocator, MimallocAllocator, registered by AddPuckAllocator | neutral README |
| Clipboard | IClipboardService: Win32ClipboardService; NullClipboardService on Linux | neutral README |
| Mouse, keyboard and pointer lock at the OS boundary | Win32NativeWindow messages, Win32RawInput (relative motion per mouse), Win32PointerLock, WindowInputQueue | pointer input |
| Pads and HID devices at the transport | WindowsInputTransports.CreateGamepadManager over Win32HidDeviceSource and Win32XboxAcquisitionSource (XInput, GameInput) | input |
| Device lights | ILampArrayDevice: Win32LampArrayDevice | abstractions |
| 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 |
| A desktop or another window's pixels as a feed | INativeImageCaptureService: Win32NativeImageCaptureService, Win32GraphicsCaptureFeed | Windows README |
| A passthrough screen that forwards input to a desktop window | Win32DesktopPassthrough, Win32PassthroughWindow | device input |
| A probe: a kernel over camera, strobe or rendered frames | ProbeReading, ProbeReadingRing, IProbeKernelHost, ProbeKernelRequest; Win32ProbeKernelBench, Win32RenderedProbeKernelHost; ProbeTrackPlayer replays recorded readings | neutral README |
| The audio output device | IAudioRenderDeviceFactory: WasapiAudioRenderDeviceFactory; none on Linux | media |
| Video encoders, loopback and microphone capture | IVideoEncoderFactory, IAudioCaptureSourceFactory: MediaFoundationVideoEncoderFactory, WasapiAudioCaptureSourceFactory; declining factories on Linux | media |
Registration shape
PlatformWindowingServiceRegistration.AddPlatformWindowingregisters only the neutral pieces (display probe, platform support, window factory). Each platform package adds one method per seam:WindowsPlatformServiceRegistration.AddWindowsPlatformWindowing,AddWindowsCameraCapture,AddWindowsRecordingPlatform,AddWindowsAudioRender,AddWindowsPrecisionWaiter, and the Linux equivalents onLinuxPlatformServiceRegistration(AddLinuxPlatformWindowing,AddLinuxCameraCapture, which registers the null camera and image-capture services today,AddLinuxRecordingPlatform). A new backend implements the contract in its platform project and replaces the null service in that platform's registration method.- A method that constructs a
[SupportedOSPlatform("windows")]type carries the attribute itself, so CA1416 makes the caller guard withOperatingSystem.IsWindows(). The guard lives in the composition root, never inside a platform project. Puck.Platform.Windowsstaysnet11.0, likePuck.Platform, so the annotations keep firing.WindowsCaptureProjection.targetsre-declares the WinRT projection at every entry point that references it, on Windows hosts.- A seam with no backend registers a null or declining service that answers
with a reason (
NullCameraCaptureService,DecliningVideoEncoderFactory), never a missing service a caller must guess about.
Play nice with the host
AGENTS.md's ruling applies here first: Puck uses the host's threads, waits, timers and virtual memory, and never spins in place of a wait or raises process-wide timer resolution. In this area that means:
- Wait on
IPrecisionWaiter.Win32HighResolutionWaitableTimerusesCREATE_WAITABLE_TIMER_HIGH_RESOLUTION, which wakes within about half a millisecond withouttimeBeginPeriodand without spinning;LauncherHostLoop.WaitUntilre-reads its clock after each wait and falls back to a one-millisecond sleep where no waiter exists. A busy loop on a stopwatch is a defect, however short. - Swap-chain waits pace a windowed host (host pacing); the timer only bounds what the swap chain cannot.
- Camera graphs own their native objects on one MTA worker thread, joined with a bound on disposal; camera scans run at most one at a time on a worker and hand back completed snapshots without blocking the caller.
- The window holds a display-required power request while open, because a powered-off display stops the compositor retiring presents.
Contracts that bite
- An empty camera list means no cameras.
EnumerateDevicesreturns empty only when the machine has none; a failed scan throwsInvalidOperationException, so a caller never reads a failed scan as every camera unplugged. - A successful open is usable. A pixel open has already published a frame from every stream; a shared open has validated native GPU input. A shared ring's consumer acquires a slot until its GPU submission retires, and the camera drops a frame rather than overwrite a texture still being sampled.
- Relative mouse motion is never integrated into a cursor estimate. Raw Input supplies per-mouse deltas; the system cursor supplies positions and buttons.
- An agent's World opens no physical device.
--devices nonedrops every OS event before a seat; never inject real input to test (puck-world). - A device or OS protocol is independent work. Consult several independent sources (vendor documentation, kernel drivers, other open implementations), cite each and note where they disagree (AGENTS.md).
Where each contract is enforced
| Contract | Enforced by |
|---|---|
| Windows-only code runs only behind an OS guard | CA1416 over [SupportedOSPlatform] on the registration methods |
Puck.Platform.Linux's closure has no Windows dependency | the Puck.Platform.Linux lane profile in build/Architecture.props (puck architecture) |
| A failed camera scan is distinct from an empty one | ICameraCaptureService.EnumerateDevices throwing; CameraDeviceScanner keeping failures apart from empty lists |
| One waiter per timer, no spinning | Win32HighResolutionWaitableTimer (one waiter at a time, re-armed per wait) |
Open gaps
- Linux has no camera, desktop-capture, audio-render, video-encoder, audio-capture or clipboard backend, and its windows hold no display request (Wayland's idle inhibit, X11's screensaver suspend). Windowed Wayland and XCB behaviour has not been run on real Linux hardware.
- Duplicates recorded in the refactoring packet: camera plane validation
and L8/BGRA packing (
Win32FaceAuthenticationCameraGraph.csbesideCameraFramePacking), and the latest-value seqlock (ProbeReadingRingbesidePuck.Hosting'sPublishBuffer<T>) (refactoring campaign). - A reading taken while the compositor is not composing still looks like a slow frame (open items).
Verify
- Build what you touched:
dotnet build src/Puck.Platform.Windows -c Releaseorsrc/Puck.Platform.Linux; a Linux change also gets the WSL2 build the Linux launcher README gives, and says what it does not prove. - Laws:
tests/Puck.Platform.Windows.Tests(camera enumeration and pixel delivery skip on a machine with no colour camera), and the host-loop laws intests/Puck.Launcher.Tests(OffscreenBoundaryLawTestsdrives a manualIPrecisionWaiter). - A window, a display, a camera or pointer lock is a windowed World, a GPU leg
(
verification); hand it back as a verification request unless your brief grants it.
Look-alikes
- Host pacing decisions (swap chain, timer grid, catch-up bursts) belong to
Puck.Launcherand the hosting reference; this area only supplies the waits and display facts they read. Puck.Inputturns transports intoInputSignals and binds them (input); this area only acquires devices and window events.- Camera capture feeds screens and probes;
capture.*records the game (media).
Route adjacent work
| Skill | Route there for |
|---|---|
input | Gamepads, HID protocols, haptics, InputArbiter, window input mapping and bindings. |
media | The audio device's mixer and director, recording sessions, encoders as the recording graph uses them. |
rendering | Swap chains, presenters, the frame pacer, shared GPU textures a camera ring feeds, the camera conversion shader. |
puck-world | Screens that show a camera or desktop feed, probes rows, booting a windowed World. |
dotnet-performance | Allocation and interop cost on a platform hot path. |
verification | GPU legs for windowed checks, the private CLI copy. |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |