waterplane 0.1.16 → 0.1.18

package/node_modules/@waterplane/shared/dist/wire/repo.d.ts

@@ -59,6 +59,11 @@ export interface GitStatus {
     upstream?: string;
     ahead: number;
     behind: number;
+    /** When this worktree last fetched (FETCH_HEAD's mtime, epoch ms) — how old `behind` is: git
+     *  counts against the remote-tracking ref, which only a fetch moves, so a repo nobody fetched
+     *  for a month read ↓0 while 30 commits waited (2026-11-03). ABSENT = never fetched from this
+     *  worktree, no upstream, or an older host. The phone cuts staleness off THIS, never off `behind`. */
+    fetchedAt?: number;
     files: GitFile[];
     clean: boolean;
     /** What the remote's own rules demand of the default branch. ABSENT = direct
@@ -72,6 +77,14 @@ export interface GitCommit {
     author: string;
     at: number;
     subject: string;
+    /** Outgoing commits only: what the pre-push checks last said about exactly this commit. */
+    check?: GitCheck;
+}
+/** One run of the pre-push hook over one commit (host `prepushcheck.ts`). Information only: the
+ *  real push still runs the hook. */
+export interface GitCheck {
+    ok: boolean;
+    at: number;
 }
 /**
  * The branch's commits against its upstream, in three disjoint lists:
@@ -91,6 +104,12 @@ export interface GitLog {
     outgoingTotal: number;
     shared: GitCommit[];
     fetchedAt?: number;
+    /** There is a pre-push hook to run; absent = none. `testsCommit`: it tests the commit it is
+     *  given, so any outgoing commit can be checked and pushed up to. Otherwise it tests the working
+     *  tree and only the newest commit can be checked. */
+    prePush?: {
+        testsCommit: boolean;
+    };
 }
 /**
  * The push the desktop is running (or last ran) in one worktree. A push runs
@@ -111,6 +130,8 @@ export interface GitPushState {
     };
     /** What the push has printed so far — absent from a host that does not stream it. */
     progress?: GitPushProgress;
+    /** This job runs the hook alone and pushes nothing. */
+    check?: boolean;
 }
 /**
  * A push's output as it streams, read by the host (`pushprogress.ts`): the
@@ -180,6 +201,9 @@ export interface RepoTarget {
      *  the branch has no upstream (nothing to count against), never 0 for that. */
     ahead?: number;
     behind?: number;
+    /** When this worktree last fetched (FETCH_HEAD's mtime) — how old `behind` is; same field and
+     *  rule as `GitStatus.fetchedAt`. ABSENT = never fetched here, no upstream, or an older host. */
+    fetchedAt?: number;
     /** Whether the repo has an `origin` remote — where the git view pushes. `false`
      *  = local only, nothing to push to (the launcher says so). ABSENT = not known
      *  (an older host, or a count not taken yet) — never drawn as "no remote". */
@@ -187,7 +211,7 @@ export interface RepoTarget {
     /** A git job the desktop is running in this worktree right now — a push (its
      *  pre-push checks take minutes) or a pull — so the launcher's git button can
      *  spin while it runs. ABSENT = none running (or an older host). */
-    gitRunning?: "push" | "pull";
+    gitRunning?: "push" | "pull" | "check";
     /** The last pull or push of a verb here FAILED and nobody has handled it —
      *  derived on the host from its attention store with `needsYou`, so this
      *  chip, the bell and the feed row are one predicate. `id` is the feed

package/node_modules/@waterplane/shared/dist/wire/repo.js.map

@@ -1 +1 @@
-{"version":3,"file":"repo.js","sourceRoot":"","sources":["../../src/wire/repo.ts"],"names":[],"mappings":"AAkbA;sEACsE;AACtE,MAAM,CAAC,MAAM,eAAe,GAAsB,CAAC,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,mBAAmB,CAAC,CAAC;AAErI;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,cAAc,CAAC,CAAkB;IAC/C,OAAO,CAAC,CAAC,KAAK,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC/F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,CAAkB;IAChD,OAAO,CAAC,CAAC,KAAK,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;AAChG,CAAC"}
+{"version":3,"file":"repo.js","sourceRoot":"","sources":["../../src/wire/repo.ts"],"names":[],"mappings":"AAycA;sEACsE;AACtE,MAAM,CAAC,MAAM,eAAe,GAAsB,CAAC,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,mBAAmB,CAAC,CAAC;AAErI;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,cAAc,CAAC,CAAkB;IAC/C,OAAO,CAAC,CAAC,KAAK,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC/F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,CAAkB;IAChD,OAAO,CAAC,CAAC,KAAK,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;AAChG,CAAC"}

package/node_modules/@waterplane/shared/dist/wire/sysstat.d.ts

@@ -61,6 +61,13 @@ export interface CpuBusy {
     /** How long the split covers, ms. A number, because a "37%" over four
      *  seconds and over four minutes are different claims. */
     spanMs: number;
+    /** Where the reading came from, when not the host OS itself: `windows` =
+     *  the Windows-wide figure read through WSL interop; `wsl-vm` = only the
+     *  WSL2 VM's own load (interop unavailable), so it under-reports the PC. */
+    source?: "windows" | "wsl-vm";
+    /** `false` when only the total is known: `userPct` then holds total busy,
+     *  `sysPct` is 0 and `cores` is empty. Absent means a real split. */
+    splitKnown?: false;
 }
 /**
  * Where the memory went.

package/node_modules/@waterplane/shared/dist/wire/telemetry.d.ts

@@ -238,6 +238,9 @@ export interface HostStat {
     loadavg: [number, number, number];
     /** 1-min load as a percent of cores (loadavg[0] / cores * 100), rounded. */
     cpuPct: number;
+    /** `windows` when `cpuPct` is the Windows-wide figure read through WSL interop
+     *  (the load average inside the VM under-reports the PC); absent otherwise. */
+    cpuSource?: "windows";
     /** Total / free physical memory, bytes. */
     memTotal: number;
     memFree: number;

package/node_modules/@waterplane/shared/package.json

@@ -10,6 +10,9 @@
       "default": "./dist/index.js"
     }
   },
+  "dependencies": {
+    "@noble/curves": "2.4.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "watch": "tsc -p tsconfig.json --watch"

package/npm-shrinkwrap.json

@@ -1,14 +1,15 @@
 {
   "name": "waterplane",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "waterplane",
-      "version": "0.1.16",
+      "version": "0.1.18",
       "license": "MIT",
       "dependencies": {
+        "@noble/curves": "2.4.0",
         "@xterm/headless": "5.5.0",
         "node-pty": "1.2.0-beta.15",
         "web-push": "3.6.7",
@@ -29,6 +30,33 @@
       "version": "0.1.4",
       "inBundle": true
     },
+    "node_modules/@noble/curves": {
+      "version": "2.4.0",
+      "resolved": "https://registry.npmjs.org/@noble/curves/-/curves-2.4.0.tgz",
+      "integrity": "sha512-P4/62zrgfH33CneE3Dn4WhJVA22YUU0eR51wKIan4NVRvwsA0YnPTwWGpNbpuacSujmSFLvyzpyuR30+fbq2Ew==",
+      "license": "MIT",
+      "dependencies": {
+        "@noble/hashes": "2.4.0"
+      },
+      "engines": {
+        "node": ">= 20.19.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@noble/hashes": {
+      "version": "2.4.0",
+      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-2.4.0.tgz",
+      "integrity": "sha512-X5XaVWZIBCT7HHZGm5I7ZQXDwLG+bGXuSrMQAW+7Zvl87h1kmc1ZB1VSRJcpUfoUrGQp4Fkoxm5kZ+Ms+aW+eA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 20.19.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
     "node_modules/@xterm/headless": {
       "version": "5.5.0",
       "resolved": "https://registry.npmjs.org/@xterm/headless/-/headless-5.5.0.tgz",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waterplane",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "type": "module",
   "description": "waterplane — phone-native remote control for Claude Code on your PC",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "node": ">=22.12"
   },
   "dependencies": {
+    "@noble/curves": "2.4.0",
     "@xterm/headless": "5.5.0",
     "node-pty": "1.2.0-beta.15",
     "web-push": "3.6.7",

package/packages/extensions/desktop/helper/Capture.swift

@@ -0,0 +1,245 @@
+// Capture: ScreenCaptureKit on one display, one window, or the frontmost
+// app's window (re-aimed at ≤1 Hz). SCK delivers a frame only when pixels
+// change (SCFrameStatus.complete); a still screen sends .idle and costs nothing.
+//
+// SAFETY: nothing in this file runs unless CGPreflightScreenCaptureAccess()
+// already says yes, so no code path here can raise the Screen Recording
+// prompt. The server checks too; `start()` checks again.
+
+import CoreGraphics
+import CoreMedia
+import Foundation
+@preconcurrency import ScreenCaptureKit
+
+private struct CaptureError: Error {
+  let sentence: String
+}
+
+final class ScreenSource: NSObject, FrameSource, SCStreamOutput, SCStreamDelegate, @unchecked Sendable {
+  private let q: DispatchQueue
+  private var p: Params
+  private let cb: SourceCallbacks
+  private var stream: SCStream?
+  private var geo: Geometry?
+  private var windowID: CGWindowID?
+  private var followTimer: DispatchSourceTimer?
+  private var stopped = false
+  private var retargeting = false
+
+  init(queue: DispatchQueue, params: Params, callbacks: SourceCallbacks) {
+    q = queue
+    p = params
+    cb = callbacks
+  }
+
+  // MARK: lifecycle (all on q)
+
+  func start() {
+    guard screenRecordingGranted() else {
+      cb.onError(screenRecordingSentence)
+      return
+    }
+    let want = p
+    Task {
+      do {
+        let content = try await SCShareableContent.excludingDesktopWindows(false, onScreenWindowsOnly: true)
+        let (filter, g, wid) = try self.resolve(content, want)
+        let s = SCStream(filter: filter, configuration: self.config(g, want), delegate: self)
+        try s.addStreamOutput(self, type: .screen, sampleHandlerQueue: self.q)
+        try await s.startCapture()
+        self.q.async {
+          if self.stopped {
+            s.stopCapture { _ in }
+            return
+          }
+          self.stream = s
+          self.windowID = wid
+          self.setGeometry(g)
+          if self.p != want { self.update(self.p) }  // params moved on while we were starting
+          if wid != nil { self.startFollowing() }
+        }
+      } catch {
+        self.q.async { self.cb.onError(Self.sentence(for: error)) }
+      }
+    }
+  }
+
+  func update(_ np: Params) {
+    let old = p
+    p = np
+    guard let s = stream, !retargeting else { return }
+    if case .window(let a) = old.source, case .window(let b) = np.source, a != b {
+      retarget(to: b)
+      return
+    }
+    guard let g = geo else { return }
+    let ng = geometry(srcWidth: g.srcWidth, srcHeight: g.srcHeight, bounds: g.globalBounds)
+    s.updateConfiguration(config(ng, np)) { err in
+      if let err { self.q.async { self.cb.onError("capture could not change settings: \(err.localizedDescription)") } }
+    }
+    setGeometry(ng)
+  }
+
+  func stop() {
+    stopped = true
+    followTimer?.cancel()
+    followTimer = nil
+    stream?.stopCapture { _ in }
+    stream = nil
+  }
+
+  // MARK: SCK callbacks
+
+  func stream(_ stream: SCStream, didOutputSampleBuffer sb: CMSampleBuffer, of type: SCStreamOutputType) {
+    guard type == .screen, sb.isValid,
+      let atts = CMSampleBufferGetSampleAttachmentsArray(sb, createIfNecessary: false) as? [[SCStreamFrameInfo: Any]],
+      let raw = atts.first?[.status] as? Int, let status = SCFrameStatus(rawValue: raw)
+    else { return }
+    switch status {
+    case .complete:
+      guard let pb = CMSampleBufferGetImageBuffer(sb) else { return }
+      let t = CMSampleBufferGetPresentationTimeStamp(sb)
+      let us = t.isValid && t.seconds > 0 ? UInt64(t.seconds * 1e6) : nowMicros()
+      cb.onFrame(pb, us)
+    case .idle:
+      cb.onIdle()
+    default:
+      break
+    }
+  }
+
+  func stream(_ stream: SCStream, didStopWithError error: Error) {
+    q.async {
+      if self.stopped { return }
+      self.cb.onError("capture stopped: " + Self.sentence(for: error))
+    }
+  }
+
+  // MARK: geometry
+
+  private func geometry(srcWidth: Int, srcHeight: Int, bounds: CGRect) -> Geometry {
+    let (w, h) = outputSize(srcW: srcWidth, srcH: srcHeight, crop: p.crop, maxWidth: p.maxWidth, codec: p.codec)
+    return Geometry(srcWidth: srcWidth, srcHeight: srcHeight, globalBounds: bounds, outWidth: w, outHeight: h)
+  }
+
+  private func setGeometry(_ g: Geometry) {
+    if g != geo {
+      geo = g
+      cb.onGeometry(g)
+    }
+  }
+
+  private func resolve(_ content: SCShareableContent, _ want: Params) throws -> (SCContentFilter, Geometry, CGWindowID?) {
+    switch want.source {
+    case .display(let id):
+      let did = id ?? CGMainDisplayID()
+      guard let d = content.displays.first(where: { $0.displayID == did }) else {
+        throw CaptureError(sentence: "Display \(did) is not active on the Mac.")
+      }
+      let mode = CGDisplayCopyDisplayMode(did)
+      let filter = SCContentFilter(display: d, excludingWindows: [])
+      let g = geometry(srcWidth: mode?.pixelWidth ?? d.width, srcHeight: mode?.pixelHeight ?? d.height,
+        bounds: CGDisplayBounds(did))
+      return (filter, g, nil)
+    case .window(let wid):
+      return try windowFilter(content, wid)
+    case .front:
+      guard let (wid, _) = windowBounds(nil) else { throw CaptureError(sentence: "No window is in front on the Mac.") }
+      return try windowFilter(content, wid)
+    case .synthetic:
+      throw CaptureError(sentence: "internal: the synthetic source is not a screen capture")
+    }
+  }
+
+  private func windowFilter(_ content: SCShareableContent, _ wid: CGWindowID) throws -> (SCContentFilter, Geometry, CGWindowID?) {
+    guard let w = content.windows.first(where: { $0.windowID == wid }) else {
+      throw CaptureError(sentence: "Window \(wid) is not on screen any more.")
+    }
+    let filter = SCContentFilter(desktopIndependentWindow: w)
+    let scale = Double(filter.pointPixelScale)
+    let bounds = windowBounds(wid)?.1 ?? w.frame
+    let g = geometry(srcWidth: Int(bounds.width * scale), srcHeight: Int(bounds.height * scale), bounds: bounds)
+    return (filter, g, wid)
+  }
+
+  private func config(_ g: Geometry, _ p: Params) -> SCStreamConfiguration {
+    let c = SCStreamConfiguration()
+    c.width = g.outWidth
+    c.height = g.outHeight
+    c.minimumFrameInterval = CMTime(value: 1, timescale: CMTimeScale(p.fps))
+    c.queueDepth = 3
+    c.showsCursor = p.cursor
+    c.capturesAudio = false
+    c.pixelFormat = pixelFormat(for: p.codec)
+    if p.codec == .h264 { c.colorMatrix = CGDisplayStream.yCbCrMatrix_ITU_R_709_2 }
+    // sourceRect is in points of the source (display-local or window-local).
+    let pw = g.globalBounds.width, ph = g.globalBounds.height
+    c.sourceRect = CGRect(x: p.crop.x * pw, y: p.crop.y * ph, width: p.crop.w * pw, height: p.crop.h * ph)
+    c.scalesToFit = true
+    return c
+  }
+
+  // MARK: following a window / the front window (≤1 Hz)
+
+  private func startFollowing() {
+    followTimer?.cancel()
+    let t = DispatchSource.makeTimerSource(queue: q)
+    t.schedule(deadline: .now() + 1, repeating: 1, leeway: .milliseconds(100))
+    t.setEventHandler { [weak self] in self?.follow() }
+    t.resume()
+    followTimer = t
+  }
+
+  private func follow() {
+    guard stream != nil, !retargeting, let g = geo else { return }
+    if case .front = p.source, let (wid, _) = windowBounds(nil), wid != windowID {
+      retarget(to: wid)
+      return
+    }
+    guard let wid = windowID else { return }
+    guard let (_, rect) = windowBounds(wid) else {
+      if case .front = p.source { return }  // the next poll picks the new front window
+      cb.onError("The captured window was closed.")
+      stop()
+      return
+    }
+    if rect != g.globalBounds {
+      let scale = g.globalBounds.width > 0 ? Double(g.srcWidth) / g.globalBounds.width : 2
+      let ng = geometry(srcWidth: Int(rect.width * scale), srcHeight: Int(rect.height * scale), bounds: rect)
+      stream?.updateConfiguration(config(ng, p)) { _ in }
+      setGeometry(ng)
+    }
+  }
+
+  private func retarget(to wid: CGWindowID) {
+    guard let s = stream else { return }
+    retargeting = true
+    let want = p
+    Task {
+      do {
+        let content = try await SCShareableContent.excludingDesktopWindows(false, onScreenWindowsOnly: true)
+        let (filter, g, _) = try self.windowFilter(content, wid)
+        try await s.updateContentFilter(filter)
+        try await s.updateConfiguration(self.config(g, want))
+        self.q.async {
+          self.retargeting = false
+          self.windowID = wid
+          self.setGeometry(g)
+          log("capture: now following window \(wid)")
+        }
+      } catch {
+        self.q.async {
+          self.retargeting = false
+          self.cb.onError(Self.sentence(for: error))
+        }
+      }
+    }
+  }
+
+  private static func sentence(for error: Error) -> String {
+    if let e = error as? CaptureError { return e.sentence }
+    let ns = error as NSError
+    if ns.domain == SCStreamErrorDomain && ns.code == SCStreamError.userDeclined.rawValue { return screenRecordingSentence }
+    return ns.localizedDescription
+  }
+}

package/packages/extensions/desktop/helper/H264.swift

@@ -0,0 +1,226 @@
+// H.264 through VideoToolbox: hardware, real-time, no B-frames, Annex-B out
+// with SPS+PPS in front of every keyframe, so any record that carries the key
+// flag is a complete entry point for a decoder that just joined.
+
+import CoreMedia
+import CoreVideo
+import Foundation
+import VideoToolbox
+
+struct EncodedFrame {
+  let data: Data
+  let key: Bool
+  let pts: UInt64
+  /// Submit → output, µs. For JPEG this is the whole synchronous encode.
+  let encodeMicros: UInt64
+  let kind: RecordKind
+  /// `avc1.PPCCLL` from the SPS, on H.264 keyframes only.
+  let avc: String?
+  /// The region the frame was submitted for, carried through the encoder so late output still
+  /// says which config produced it.
+  let region: Region
+}
+
+protocol FrameEncoder: AnyObject {
+  var width: Int { get }
+  var height: Int { get }
+  var codec: Codec { get }
+  /// Frames submitted and not yet out. The server drops new frames past a few.
+  var inFlight: Int { get }
+  func encode(_ pb: CVPixelBuffer, pts: UInt64, forceKey: Bool, region: Region)
+  /// Same size and codec, new knobs (bitrate, fps, keyframe interval, quality…).
+  func update(_ p: Params)
+  func setBitrate(_ kbps: Int)
+  func invalidate()
+}
+
+final class H264Encoder: FrameEncoder {
+  let width: Int
+  let height: Int
+  let codec = Codec.h264
+  private(set) var profile = "main"
+  private(set) var hardware = false
+  private var session: VTCompressionSession?
+  private let sink: (EncodedFrame) -> Void
+  private let lock = NSLock()
+  private var submitted: [UInt64: UInt64] = [:]
+  private var pending = 0
+  private var params: Params
+
+  var inFlight: Int {
+    lock.lock()
+    defer { lock.unlock() }
+    return pending
+  }
+
+  init?(width: Int, height: Int, params: Params, sink: @escaping (EncodedFrame) -> Void) {
+    self.width = width
+    self.height = height
+    self.params = params
+    self.sink = sink
+    let spec: [String: Any] = [
+      kVTVideoEncoderSpecification_EnableHardwareAcceleratedVideoEncoder as String: true
+    ]
+    var s: VTCompressionSession?
+    let st = VTCompressionSessionCreate(
+      allocator: nil, width: Int32(width), height: Int32(height), codecType: kCMVideoCodecType_H264,
+      encoderSpecification: spec as CFDictionary, imageBufferAttributes: nil, compressedDataAllocator: nil,
+      outputCallback: nil, refcon: nil, compressionSessionOut: &s)
+    guard st == noErr, let s else {
+      log("h264: VTCompressionSessionCreate \(width)x\(height) failed (\(st))")
+      return nil
+    }
+    session = s
+    set(kVTCompressionPropertyKey_RealTime, kCFBooleanTrue)
+    set(kVTCompressionPropertyKey_AllowFrameReordering, kCFBooleanFalse)
+    if set(kVTCompressionPropertyKey_ProfileLevel, kVTProfileLevel_H264_Main_AutoLevel, quiet: true) != noErr {
+      set(kVTCompressionPropertyKey_ProfileLevel, kVTProfileLevel_H264_Baseline_AutoLevel)
+      profile = "baseline"
+    } else {
+      set(kVTCompressionPropertyKey_H264EntropyMode, kVTH264EntropyMode_CABAC, quiet: true)
+    }
+    set(kVTCompressionPropertyKey_MaxFrameDelayCount, 0 as NSNumber, quiet: true)
+    set(kVTCompressionPropertyKey_PrioritizeEncodingSpeedOverQuality, kCFBooleanTrue, quiet: true)
+    applyRate(params.bitrateKbps)
+    applyTiming(params)
+    var hw: Unmanaged<CFTypeRef>?
+    if VTSessionCopyProperty(s, key: kVTCompressionPropertyKey_UsingHardwareAcceleratedVideoEncoder,
+      allocator: nil, valueOut: &hw) == noErr, let b = hw?.takeRetainedValue() as? Bool
+    {
+      hardware = b
+    }
+    VTCompressionSessionPrepareToEncodeFrames(s)
+    log("h264: \(width)x\(height) \(profile) \(hardware ? "hardware" : "software") \(params.bitrateKbps) kbps \(params.fps) fps")
+  }
+
+  deinit { invalidate() }
+
+  @discardableResult
+  private func set(_ k: CFString, _ v: CFTypeRef?, quiet: Bool = false) -> OSStatus {
+    guard let session else { return -1 }
+    let st = VTSessionSetProperty(session, key: k, value: v)
+    if st != noErr && !quiet { log("h264: setting \(k) failed (\(st))") }
+    return st
+  }
+
+  private func applyRate(_ kbps: Int) {
+    let bps = kbps * 1000
+    set(kVTCompressionPropertyKey_AverageBitRate, bps as NSNumber)
+    // Hard ceiling: 1.5× the average over any 1 s window.
+    let limits = [NSNumber(value: Double(bps) / 8 * 1.5), NSNumber(value: 1.0)] as CFArray
+    set(kVTCompressionPropertyKey_DataRateLimits, limits)
+  }
+
+  private func applyTiming(_ p: Params) {
+    set(kVTCompressionPropertyKey_ExpectedFrameRate, p.fps as NSNumber)
+    if p.keyframeEverySec > 0 {
+      set(kVTCompressionPropertyKey_MaxKeyFrameInterval, max(1, Int((p.keyframeEverySec * Double(p.fps)).rounded())) as NSNumber)
+      set(kVTCompressionPropertyKey_MaxKeyFrameIntervalDuration, p.keyframeEverySec as NSNumber)
+    } else {
+      // On demand only: an interval nobody reaches (a day of frames at 60 fps).
+      set(kVTCompressionPropertyKey_MaxKeyFrameInterval, 5_184_000 as NSNumber)
+      set(kVTCompressionPropertyKey_MaxKeyFrameIntervalDuration, 86_400 as NSNumber)
+    }
+  }
+
+  func update(_ p: Params) {
+    if p.bitrateKbps != params.bitrateKbps { applyRate(p.bitrateKbps) }
+    if p.fps != params.fps || p.keyframeEverySec != params.keyframeEverySec { applyTiming(p) }
+    params = p
+  }
+
+  func setBitrate(_ kbps: Int) {
+    params.bitrateKbps = kbps
+    applyRate(kbps)
+  }
+
+  func invalidate() {
+    if let s = session { VTCompressionSessionInvalidate(s) }
+    session = nil
+  }
+
+  func encode(_ pb: CVPixelBuffer, pts: UInt64, forceKey: Bool, region: Region) {
+    guard let s = session else { return }
+    let t = CMTime(value: CMTimeValue(pts), timescale: 1_000_000)
+    let props: CFDictionary? =
+      forceKey ? [kVTEncodeFrameOptionKey_ForceKeyFrame as String: true] as CFDictionary : nil
+    lock.lock()
+    submitted[pts] = nowMicros()
+    pending += 1
+    lock.unlock()
+    let st = VTCompressionSessionEncodeFrame(
+      s, imageBuffer: pb, presentationTimeStamp: t, duration: .invalid, frameProperties: props, infoFlagsOut: nil
+    ) { [weak self] status, flags, sb in
+      self?.output(status, flags, sb, pts, region)
+    }
+    if st != noErr {
+      log("h264: encode failed (\(st))")
+      lock.lock()
+      submitted[pts] = nil
+      pending -= 1
+      lock.unlock()
+    }
+  }
+
+  private func output(_ status: OSStatus, _ flags: VTEncodeInfoFlags, _ sb: CMSampleBuffer?, _ pts: UInt64, _ region: Region) {
+    lock.lock()
+    let sub = submitted.removeValue(forKey: pts)
+    pending -= 1
+    lock.unlock()
+    guard status == noErr, let sb, let bb = CMSampleBufferGetDataBuffer(sb) else {
+      if status != noErr { log("h264: encoder returned \(status)") }
+      return
+    }
+    var key = true
+    if let arr = CMSampleBufferGetSampleAttachmentsArray(sb, createIfNecessary: false) as? [[CFString: Any]],
+      let a = arr.first, let notSync = a[kCMSampleAttachmentKey_NotSync] as? Bool
+    {
+      key = !notSync
+    }
+    let total = CMBlockBufferGetDataLength(bb)
+    var avcc = Data(count: total)
+    let copied = avcc.withUnsafeMutableBytes { CMBlockBufferCopyDataBytes(bb, atOffset: 0, dataLength: total, destination: $0.baseAddress!) }
+    guard copied == kCMBlockBufferNoErr else { return }
+
+    let startCode: [UInt8] = [0, 0, 0, 1]
+    var out = Data(capacity: total + 64)
+    var nalLen: Int32 = 4
+    var avc: String?
+    if let fd = CMSampleBufferGetFormatDescription(sb) {
+      var count = 0
+      CMVideoFormatDescriptionGetH264ParameterSetAtIndex(
+        fd, parameterSetIndex: 0, parameterSetPointerOut: nil, parameterSetSizeOut: nil,
+        parameterSetCountOut: &count, nalUnitHeaderLengthOut: &nalLen)
+      if key {
+        for i in 0..<count {
+          var p: UnsafePointer<UInt8>?
+          var n = 0
+          guard CMVideoFormatDescriptionGetH264ParameterSetAtIndex(
+            fd, parameterSetIndex: i, parameterSetPointerOut: &p, parameterSetSizeOut: &n,
+            parameterSetCountOut: nil, nalUnitHeaderLengthOut: nil) == noErr, let p
+          else { continue }
+          out.append(contentsOf: startCode)
+          out.append(p, count: n)
+          if i == 0 && n >= 4 { avc = String(format: "avc1.%02x%02x%02x", p[1], p[2], p[3]) }
+        }
+      }
+    }
+    // AVCC length prefixes → Annex-B start codes.
+    let L = Int(nalLen)
+    avcc.withUnsafeBytes { raw in
+      let b = raw.bindMemory(to: UInt8.self)
+      var off = 0
+      while off + L <= total {
+        var len = 0
+        for i in 0..<L { len = (len << 8) | Int(b[off + i]) }
+        off += L
+        guard len > 0, off + len <= total else { break }
+        out.append(contentsOf: startCode)
+        out.append(b.baseAddress! + off, count: len)
+        off += len
+      }
+    }
+    let enc = sub.map { nowMicros() &- $0 } ?? 0
+    sink(EncodedFrame(data: out, key: key, pts: pts, encodeMicros: enc, kind: .h264, avc: avc, region: region))
+  }
+}

package/packages/extensions/desktop/helper/Info.plist

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleIdentifier</key>
+  <string>@WP_DESKTOP_ID@</string>
+  <key>CFBundleName</key>
+  <string>wp-desktop</string>
+  <key>CFBundleDisplayName</key>
+  <string>@WP_DESKTOP_NAME@</string>
+  <key>CFBundleShortVersionString</key>
+  <string>0.1.0</string>
+  <key>CFBundleVersion</key>
+  <string>1</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>LSMinimumSystemVersion</key>
+  <string>14.0</string>
+</dict>
+</plist>