The preview instrumentation is `print` — convert it, but keep the shape

[liversedge]

From PinPointStudio's preview handover, 28 August 2026, §4.3.

What is committed, and why

LivePreview and AppModel carry print("[preview] …") calls — committed deliberately, by them, because this application has no logging framework and print on a device console is what made nine defects findable at all. Reading it took about ninety seconds and should have been the first thing anyone did.

Sources/Platform/Capture/LivePreview.swift:174   print("[preview] sent=\(segmentsSent) tapped=\(framesTapped)")
Sources/Platform/Capture/LivePreview.swift:182   print("[preview] REFUSED after \(framesTapped) frame(s): \(text)")

The ask, which is about shape and not about print

Convert it to whatever this application adopts — but keep the shape:

• Per-stage counters, not one boolean. framesTapped, segmentsSent, lastError are three numbers whose first zero names the break: tapped 0 means the camera is not feeding, tapped>0 with sent 0 means the producer is refusing, sent>0 with a black tile means it is the wire or the host.
• A named reason, verbatim, on every refusal. "It did not work" is what cost the two days.

⚠ Every preview refusal now names itself. Do not lose that in the conversion.

Where it belongs

This is E10's territory — #48 (E10.1, one file a maintainer can diagnose from) and #50 (E10.3, diagnostic mode). ⚠ Do not strip the prints before their replacement exists — the next hardware session still needs them.

Exit criterion

The preview path logs through the adopted framework, the three counters survive into the diagnostic bundle, and a refusal's reason appears there verbatim.

[liversedge]

The application adopted something. PpcpLog, 30 August — 8201ec8

This issue asked to "convert it to whatever this application adopts", and until 30 August there was nothing to convert to. There is now, and it was built for the same reason this issue exists.

Sources/Platform/Diagnostics/PpcpLog.swift writes to both:

• the unified log, which is what idevicesyslog reads, and which Linux already has since libimobiledevice is the usbmux prerequisite;
• stdout, which is what devicectl --console bridges.

⚠ Neither is a superset, which 8201ec8 found the hard way trying to read a cabled phone from a Mac with no libimobiledevice installed. That is why it is both and not one.

Today it is called from AppModel and PpcpTransport only — per-channel dialled / link_bind sent / link_bind FAILED, link lost with its error, presence up/down/failed with the count. No key, no identity, no payload; session ids only.

⛔ The preview prints are untouched, and that is correct for now

Sources/Platform/Capture/LivePreview.swift:125  print("[preview] tap attached source=…")
Sources/Platform/Capture/LivePreview.swift:151  print("[preview] first frame ptsNs=… openedAtNs=…")
Sources/Platform/Capture/LivePreview.swift:174  print("[preview] sent=\(segmentsSent) tapped=\(framesTapped)")
Sources/Platform/Capture/LivePreview.swift:182  print("[preview] REFUSED after \(framesTapped) frame(s): \(text)")
Sources/App/AppModel.swift:1754                 print("[preview] OPENED source=… profile=…")
Sources/App/AppModel.swift:1756                 print("[preview] REFUSED source=… reason=…")

⚠ This issue says do not strip them before their replacement exists, and the next hardware session still needs them. PpcpLog is the replacement, so the conversion is now unblocked — but it must go through PpcpLog, not straight to stdout, or a cabled phone loses the one channel that made the wired faults diagnosable.

The ask is unchanged and it is about shape: the three counters whose first zero names the break, and a named reason verbatim on every refusal. Do not lose either in the conversion, and carry them into E10's bundle (#48, #50).

[liversedge]

The destination now exists — the conversion still has not happened

This issue asks for the print("[preview] …") instrumentation to be converted while keeping its shape. Two things landed in between that decide what it converts to:

• PpcpLog (8201ec8) writes to both the unified log and stdout. Neither is a superset: idevicesyslog reads the legacy syslog relay and carries the unified log, devicectl … --console bridges stdout.
• ⛔ PpcpDiagnostics (97133f1, c382888) is the one that matters on a cabled phone, and the reason is measured rather than stylistic: devicectl --console holds a CoreDevice tunnel that re-enumerates the device and kills the link being measured. Every PpcpLog category now also goes to a bounded 256 KB file in Documents, off the caller's thread, never throwing, no key material and no payload — pulled with make pull-diags, which touches nothing.

So the shape this issue asks to preserve now has somewhere to go, with categories already in use: ppcp.link, ppcp.transfer.

⛔ Unchanged: the preview path is still print

Sources/App/AppModel.swift:2190,2192
Sources/App/HostLinkSession.swift:943,952,975,999,1009
Sources/Platform/Capture/LivePreview.swift:125,151,174,182
Sources/Platform/Capture/PreviewFrameTap.swift:87,100

Thirteen call sites, and on a cabled phone every one of them is unreadable — which is precisely the condition preview is now most often exercised under, since preview over USB started working on 31 August (e2a9f70). ⚠ The counters and the named reason are the part worth keeping: sent=N tapped=N and REFUSED after N frame(s): reason are what turned five stacked invisible defects into five sequential visible ones.