@pictor-sdk/video-android 0.1.0

package/src/media3.ts

@@ -0,0 +1,412 @@
+import { type PlaylistResult } from '@pictor-sdk/video-core'
+import { requireNative } from './player'
+
+/**
+ * Playback backed by Media3's ExoPlayer.
+ *
+ * Media3 owns decoding, buffering, audio focus, synchronisation, seeking, speed
+ * and lifecycle. Pictor owns the document, the timeline and the Skia
+ * composition. This is the whole of the seam between them.
+ *
+ * **No Media3 or Android type appears here.** Positions are microseconds
+ * because that is Pictor's unit; the adapter converts.
+ *
+ * Video is rendered into the persistent external texture, so the renderer holds
+ * one `SkImage` for a whole session and nothing is imported per frame.
+ *
+ * @experimental
+ */
+export interface Media3State {
+  positionUs: number
+  durationUs: number
+  playing: boolean
+  buffering: boolean
+  ready: boolean
+  ended: boolean
+  rate: number
+  width: number
+  height: number
+  released: boolean
+  error: string
+  /** Bumped on seek, source change and release; pairs frames with a clip. */
+  generation: number
+  /** Frame metadata awaiting a renderer. Bounded. */
+  queueDepth: number
+  /** Metadata dropped because the queue was full. Should stay zero. */
+  overflowed: number
+  /** Frames consumed with no sample to pair. Expected briefly after a seek. */
+  unpaired: number
+  /** Samples discarded because their generation was superseded. */
+  stale: number
+  queueHighWater: number
+  /** Live threads in the process. Diagnostics for leak attribution. */
+  threads: number
+  /** Allocated native heap, for the safety cutoff. */
+  nativeHeapBytes: number
+  /** The anchor's own position, before extrapolation. Diagnostics. */
+  anchorPositionUs: number
+  /** Frames the buffer queue dropped because the renderer was behind. */
+  coalesced: number
+  /** How coarse `Player.currentPosition` is, measured rather than assumed. */
+  anchorPublications: number
+  anchorChanges: number
+  anchorMaxStepUs: number
+  anchorMeanStepUs: number
+  anchorMaxStaleNs: number
+  /** Which playlist window is playing, and how many there are. */
+  windowIndex: number
+  windowCount: number
+  /** Offset inside the current window, in microseconds. */
+  windowPositionUs: number
+  /** Window transitions so far — seams crossed. Diagnostics. */
+  transitions: number
+  /**
+   * Frames whose latch failed and was retried on the next tick.
+   *
+   * `updateTexImage` returns quietly when Skia's GL context is not current on
+   * the calling thread, so this counts the retries rather than letting the
+   * frames disappear. A handful around startup and playlist changes is normal;
+   * a rate that tracks the frame rate is not.
+   */
+  missedLatches: number
+  /**
+   * What the single latch owner did, per frame.
+   *
+   * `skipped` counts ticks refused because the surface was retired or replaced
+   * — the invalid call, prevented rather than caught. `failed` must stay
+   * visible: a latch that quietly does nothing looks exactly like a paused
+   * video, which is how an earlier defect hid for a whole session.
+   */
+  updatesAttempted: number
+  updatesSucceeded: number
+  updatesSkipped: number
+  updatesFailed: number
+  /**
+   * Times a requested rate exceeded the range and had to be clamped.
+   *
+   * Should stay zero: the UI only offers rates that compose within range. A
+   * non-zero value means the picture and the timeline are counting differently.
+   */
+  rateConstrained: number
+  /** The rate actually in force: clip speed times preview rate, clamped. */
+  effectiveRate: number
+  /**
+   * The rate asked for, before clamping.
+   *
+   * Beside `effectiveRate` this says whether a ceiling was *selected* or merely
+   * reached: 10 requested and 10 effective is a legitimate extreme, while 25
+   * requested and 10 effective is a refusal.
+   */
+  requestedRate: number
+  /**
+   * Window indices that had no speed. Should stay zero.
+   *
+   * Non-zero means the playlist and the window index were read at different
+   * moments — the shape that left a cleared playlist running at the rate of the
+   * playlist before it.
+   */
+  staleWindowSpeeds: number
+  /** How many per-window speeds the player holds. Zero when idle. */
+  windowSpeedCount: number
+  /**
+   * The two halves of frame delivery, counted separately.
+   *
+   * `framesOffered` is Media3 telling us a frame is about to be released;
+   * `framesAvailable` is the SurfaceTexture saying one arrived. If the first
+   * climbs while the second does not, the decoder is running but its output is
+   * not reaching our surface — which is a completely different fault from the
+   * renderer failing to pull.
+   */
+  framesOffered: number
+  framesAvailable: number
+  /**
+   * Frames waiting to be latched, right now.
+   *
+   * A level rather than an edge, so it survives the consumer being disarmed.
+   * Usually 0 or 1; larger after a background, and it must fall to 0 within a
+   * tick of the consumer re-arming.
+   */
+  pendingDepth: number
+  /** Availability announced for a generation already retired. Should stay 0. */
+  framesRejected: number
+  /**
+   * The generation the pending counters are keeping for.
+   *
+   * Must equal the consumer's generation. A frame pending for a different one
+   * is a frame nobody will ever take.
+   */
+  pendingGeneration: number
+  /** Producer identity, for proving which object a consumer is holding. */
+  controllerId: number
+  pendingId: number
+  orphaned: number
+  /** `mime WxH rotN @fps` for the active item. Empty when there is no video. */
+  videoFormat: string
+  /** The decoder Media3 selected, e.g. `c2.exynos.h264.decoder`. */
+  decoderName: string
+  /**
+   * What the decoder was configured for, and what it produced.
+   *
+   * Read from the player's own events rather than inferred from the device: a
+   * mixed-resolution seam is the one moment input and output can disagree, and
+   * naming the decoder from the model instead of asking is how an attribution
+   * survives without ever being checked.
+   */
+  inputFormats: number
+  inputWidth: number
+  inputHeight: number
+  inputRotation: number
+  /** Media3's decoder-reuse verdict across the last format change; -1 if none. */
+  decoderReuse: number
+  outputSizes: number
+  outputWidth: number
+  outputHeight: number
+  /** Increments on each decoder init — makes re-attachment visible. */
+  surfaceGeneration: number
+  /**
+   * Seek bookkeeping for the cross-window freeze soak.
+   *
+   * `seeksRequested` counts calls; `seeksAccepted` counts those the player's
+   * own thread acted on. A gap between them, or a `pendingSeek` that stays
+   * true, is a seek that never reached the player — which is what the observed
+   * freeze would look like from this side.
+   */
+  /**
+   * Surface attachment bookkeeping, for diagnostics only.
+   *
+   * The adapter attaches automatically the instant a surface becomes live, so a
+   * host never calls anything. These exist so the invariant can be *checked*:
+   * `attachedSurfaceGeneration` trailing `liveSurfaceGeneration` means the
+   * player is rendering into a surface nobody is watching.
+   */
+  surfaceAttachments: number
+  attachedSurfaceGeneration: number
+  liveSurfaceGeneration: number
+  seeksRequested: number
+  seeksAccepted: number
+  pendingSeek: boolean
+  /** Media3's own playback state constant. 1 idle, 2 buffering, 3 ready, 4 ended. */
+  playbackState: number
+  /** PTS of the last frame the renderer actually paired, or -1. */
+  lastPairedPtsUs: number
+  /**
+   * Source failures reported by the player, not inferred from the state.
+   *
+   * A failed source otherwise looks exactly like an idle one — nothing playing,
+   * nothing buffering, no duration — so the count is what distinguishes "never
+   * started" from "started and broke".
+   */
+  errorCount: number
+  /** Media3's error code, and its name plus message. Empty when healthy. */
+  errorCode: number
+  errorMessage: string
+  /** Whether Media3 classifies the failure as worth retrying. */
+  errorRecoverable: boolean
+}
+
+const EMPTY: Media3State = {
+  positionUs: 0,
+  durationUs: 0,
+  playing: false,
+  buffering: false,
+  ready: false,
+  ended: false,
+  rate: 1,
+  width: 0,
+  height: 0,
+  released: true,
+  error: '',
+  generation: 0,
+  queueDepth: 0,
+  overflowed: 0,
+  unpaired: 0,
+  stale: 0,
+  queueHighWater: 0,
+  threads: 0,
+  nativeHeapBytes: 0,
+  anchorPositionUs: 0,
+  coalesced: 0,
+  anchorPublications: 0,
+  anchorChanges: 0,
+  anchorMaxStepUs: 0,
+  anchorMeanStepUs: 0,
+  anchorMaxStaleNs: 0,
+  windowIndex: 0,
+  windowCount: 0,
+  windowPositionUs: 0,
+  transitions: 0,
+  missedLatches: 0,
+  updatesAttempted: 0,
+  updatesSucceeded: 0,
+  updatesSkipped: 0,
+  updatesFailed: 0,
+  rateConstrained: 0,
+  effectiveRate: 1,
+  requestedRate: 1,
+  staleWindowSpeeds: 0,
+  windowSpeedCount: 0,
+  framesOffered: 0,
+  framesAvailable: 0,
+  pendingDepth: 0,
+  framesRejected: 0,
+  pendingGeneration: 0,
+  controllerId: 0,
+  pendingId: 0,
+  orphaned: 0,
+  videoFormat: '',
+  decoderName: '',
+  inputFormats: 0,
+  inputWidth: 0,
+  inputHeight: 0,
+  inputRotation: 0,
+  decoderReuse: -1,
+  outputSizes: 0,
+  outputWidth: 0,
+  outputHeight: 0,
+  surfaceGeneration: 0,
+  surfaceAttachments: 0,
+  attachedSurfaceGeneration: 0,
+  liveSurfaceGeneration: 0,
+  seeksRequested: 0,
+  seeksAccepted: 0,
+  pendingSeek: false,
+  playbackState: 0,
+  lastPairedPtsUs: -1,
+  errorCount: 0,
+  errorCode: 0,
+  errorMessage: '',
+  errorRecoverable: false,
+}
+
+/** @experimental */
+export const Media3 = {
+  /**
+   * Open a local clip and render it into the presentation surface.
+   *
+   * The surface must already exist: it is created on the UI runtime, where
+   * Skia's GL context lives, and preparing without one is an error rather than
+   * a silently black picture.
+   */
+  prepare(uri: string): boolean {
+    return requireNative().media3Prepare(uri)
+  },
+
+  /** Diagnostics: a player with no video output, for heap attribution. */
+  prepareNoSurface(uri: string): boolean {
+    return requireNative().media3PrepareNoSurface(uri)
+  },
+
+  /** Diagnostics: reuse the existing player for another source. */
+  rebind(uri: string): boolean {
+    return requireNative().media3Rebind(uri)
+  },
+
+  /** Diagnostics: end the source, keep the player. */
+  stopKeepingPlayer(): void {
+    requireNative().media3StopKeepingPlayer()
+  },
+
+  /**
+   * Replace the playlist from a project's playable windows.
+   *
+   * Takes the `PlaylistResult` straight from `@pictor-sdk/video-core` so the
+   * project → window mapping has exactly one definition, tested there as a
+   * round trip.
+   * The sources must already be URI strings; this adapter does not interpret a
+   * host's media descriptors, and a non-URI source is a host normalisation bug
+   * rather than something to guess at.
+   *
+   * The OES texture and the `SkImage` survive this. Changing the playlist is
+   * not a reason to rebuild what the renderer holds.
+   */
+  setPlaylist(
+    playlist: PlaylistResult,
+    start: { windowIndex: number; positionUs: number } = { windowIndex: 0, positionUs: 0 },
+    options: { allowDivergence?: boolean } = {},
+  ): boolean {
+    // Refuse a playlist that would not play what the timeline shows.
+    //
+    // An unsupported clip keeps its span on the timeline while contributing
+    // nothing to playback, so the two clocks diverge by exactly its duration
+    // and every seam after it lands wrong. That is far worse than an error: it
+    // looks like a working editor that is slightly out of sync. A host that
+    // genuinely wants the playable remainder must ask for it.
+    if (playlist.unsupported.length > 0 && options.allowDivergence !== true) {
+      throw new Error(
+        '@pictor-sdk/video-android: refusing to build a playlist that would diverge from the ' +
+          `timeline. ${playlist.unsupported.length} clip(s) cannot play:\n` +
+          playlist.unsupported.map((u) => `  · ${u.message}`).join('\n') +
+          '\nPass { allowDivergence: true } to play the remainder anyway.',
+      )
+    }
+    const uris: string[] = []
+    const bounds: number[] = []
+    for (const item of playlist.items) {
+      uris.push(uriOf(item.source))
+      bounds.push(item.startUs, item.endUs, Math.round(item.speed * 1000), item.muted ? 1 : 0)
+    }
+    return requireNative().media3SetPlaylist(uris, bounds, start.windowIndex, start.positionUs)
+  },
+
+  /** Seek in the player's coordinates. Pair with `projectTimeToWindow`. */
+  seekToWindow(windowIndex: number, positionUs: number): void {
+    requireNative().media3SeekToWindow(windowIndex, positionUs)
+  },
+
+  play(): void {
+    requireNative().media3Play()
+  },
+
+  pause(): void {
+    requireNative().media3Pause()
+  },
+
+  /** Microseconds, like every other time in Pictor. */
+  seek(positionUs: number): void {
+    requireNative().media3Seek(positionUs)
+  },
+
+  setRate(rate: number): void {
+    requireNative().media3SetRate(rate)
+  },
+
+  /**
+   * Try the current source again after a failure.
+   *
+   * This is Media3's own recovery path: it re-resolves the source and resumes
+   * from the current position. Worth calling when `errorRecoverable` is true —
+   * a network source that went away and came back — and pointless otherwise.
+   */
+  retry(): void {
+    requireNative().media3Retry()
+  },
+
+  release(): void {
+    requireNative().media3Release()
+  },
+
+  /** A snapshot for throttled reads. Never call this per frame. */
+  state(): Media3State {
+    const raw = requireNative().media3State() as Partial<Media3State> | null
+    return raw ? { ...EMPTY, ...raw } : EMPTY
+  },
+}
+
+/**
+ * A source as a URI string, or a readable failure.
+ *
+ * `MediaSource` is deliberately open — the timeline stores whatever descriptor
+ * a host uses — so the adapter is where it has to become something Android can
+ * open. Failing loudly here is better than handing `undefined` to `Uri.parse`
+ * and getting a black picture with no explanation.
+ */
+function uriOf(source: unknown): string {
+  if (typeof source === 'string') return source
+  if (source && typeof source === 'object' && 'uri' in source) {
+    const uri = (source as { uri?: unknown }).uri
+    if (typeof uri === 'string') return uri
+  }
+  throw new Error(
+    `@pictor-sdk/video-android: a clip's source is not a URI. Normalise host media to { kind: 'uri', uri } before opening a project. Received: ${JSON.stringify(source)}`,
+  )
+}

package/src/mediaStore.ts

@@ -0,0 +1,177 @@
+import type { MediaSaver, SavedMedia } from '@pictor-sdk/video-core'
+import NativePictorVideoModule from './NativePictorVideo'
+
+/**
+ * Saving a finished export into Android's video collection.
+ *
+ * A thin boundary. The insert-pending / stream / verify / publish sequence is
+ * native, because it is where the file descriptors and the cancellation live;
+ * this turns one JSON result into either a {@link SavedMedia} or a typed error,
+ * and gives every save an id so a cancel reaches the right one.
+ *
+ * ## What a failure guarantees
+ *
+ * Nothing partial. Every unsuccessful native path — a short write, a full disk,
+ * a cancellation, an unreadable result — deletes the pending row before
+ * returning, and a pending row was never visible to the gallery in the first
+ * place. So a failed save leaves the collection exactly as it was.
+ *
+ * ## What it never does
+ *
+ * Delete a published item. Releasing the export's temporary is a separate act
+ * on a separate file, and a saved video belongs to the user from the moment it
+ * is published.
+ *
+ * @experimental
+ */
+
+/** Why a save did not happen. @experimental */
+export class MediaSaveFailed extends Error {
+  /** Safe to display: never a path, a stack, or a platform message. */
+  readonly reason: string
+  constructor(reason: string) {
+    super(`save failed: ${reason}`)
+    this.name = 'MediaSaveFailed'
+    this.reason = reason
+  }
+}
+
+/** A save the user asked to stop. @experimental */
+export class MediaSaveCancelled extends Error {
+  constructor() {
+    super('save cancelled')
+    this.name = 'MediaSaveCancelled'
+  }
+}
+
+/**
+ * Offer a saved video to the system share sheet.
+ *
+ * Only after a successful save, and only ever the durable `content:` uri. The
+ * cache path the export produced is app-private: a receiver could not open it,
+ * and handing one out is the mistake `FileUriExposedException` exists to catch.
+ *
+ * Sharing changes nothing. The same row is offered every time — no copy, no
+ * rename, no re-publish, and nothing released.
+ *
+ * Returns `false` when the device has nothing that accepts a video, which is an
+ * outcome rather than a failure: the saved video is untouched either way.
+ *
+ * @experimental
+ */
+export function shareSavedMedia(uri: string): { ok: boolean; noTargets: boolean; reason: string } {
+  if (!NativePictorVideoModule) {
+    return { ok: false, noTargets: false, reason: 'sharing is not available' }
+  }
+  if (!uri.startsWith('content://')) {
+    /*
+      Refused rather than attempted.
+
+      The only uri worth sharing is the published one. A cache path reaching
+      here would mean the save had not happened, and offering it would either
+      throw on a modern target or hand a receiver something it cannot read.
+    */
+    return { ok: false, noTargets: false, reason: 'only a saved video can be shared' }
+  }
+  const result = JSON.parse(NativePictorVideoModule.mediaShare(uri)) as {
+    ok?: boolean
+    noTargets?: boolean
+    error?: string
+  }
+  return {
+    ok: result.ok === true,
+    noTargets: result.noTargets === true,
+    reason: result.error ?? '',
+  }
+}
+
+let counter = 0
+
+/** @experimental */
+export function createMediaStoreSaver(): MediaSaver {
+  /*
+    The job whose cancel is live.
+
+    Held so a cancel arriving after one save settled cannot stop the next: the
+    id is checked natively, and clearing it here means a stray press reaches
+    nothing at all.
+  */
+  let active: string | null = null
+
+  const native = () => {
+    if (!NativePictorVideoModule) {
+      throw new MediaSaveFailed('the Pictor video native module is not installed')
+    }
+    return NativePictorVideoModule
+  }
+
+  return {
+    async save(sourceUri: string): Promise<SavedMedia> {
+      if (active !== null) {
+        // Refused rather than queued: two saves of the same export would insert
+        // two rows, and the user asked for one video.
+        throw new MediaSaveFailed('a save is already running')
+      }
+      counter += 1
+      const id = `save_${counter.toString(36)}`
+      active = id
+      let outcome: {
+        ok: boolean
+        uri?: string
+        displayName?: string
+        location?: string
+        error?: string
+        cancelled?: boolean
+      }
+      try {
+        outcome = JSON.parse(await native().mediaSaveAsync(id, sourceUri))
+      } finally {
+        active = null
+      }
+      if (outcome.cancelled === true) throw new MediaSaveCancelled()
+      if (!outcome.ok || typeof outcome.uri !== 'string') {
+        throw new MediaSaveFailed(outcome.error ?? 'the file could not be saved')
+      }
+      return {
+        uri: outcome.uri,
+        displayName: outcome.displayName ?? '',
+        location: outcome.location ?? '',
+      }
+    },
+
+    cancel(): void {
+      if (active === null) return
+      native().mediaSaveCancel(active)
+    },
+  }
+}
+
+/**
+ * Delete pending rows a killed process left behind.
+ *
+ * Worth calling once at startup. A pending row is invisible to the gallery and
+ * still occupies storage, so nothing will ever prompt a user to clean one up.
+ *
+ * Scoped to this app's own still-pending rows under its own folder: a published
+ * item is never a candidate, and neither is anything another app wrote.
+ *
+ * @experimental
+ */
+export function sweepPendingMediaSaves(): {
+  swept: number
+  inspected: number
+  /** Pending rows seen and deliberately left alone. */
+  skipped: number
+} {
+  if (!NativePictorVideoModule) return { swept: 0, inspected: 0, skipped: 0 }
+  const result = JSON.parse(NativePictorVideoModule.mediaSaveSweepPending()) as {
+    swept?: number
+    inspected?: number
+    skipped?: number
+  }
+  return {
+    swept: result.swept ?? 0,
+    inspected: result.inspected ?? 0,
+    skipped: result.skipped ?? 0,
+  }
+}

package/src/memoryGuard.ts

@@ -0,0 +1,118 @@
+/**
+ * A debug safety cutoff on native memory.
+ *
+ * **Remove before production.** This exists because an earlier revision drove
+ * the native heap to 1.5 GB in sixty seconds and the process was killed —
+ * taking other applications on the device with it, since Android reclaims from
+ * everything before it gives up on the foreground app. A diagnostic run must
+ * not be able to do that again.
+ *
+ * Two independent triggers, because a leak can be fast or merely relentless:
+ *
+ * - **Ceiling.** An absolute limit, well under anything that would put the
+ *   device under pressure.
+ * - **Sustained rise.** Memory that climbs across every sample of a window with
+ *   no plateau, which is what a slow leak looks like and what a ceiling alone
+ *   would take minutes to catch.
+ *
+ * Pure, so the rule is tested rather than trusted: a cutoff that misfires stops
+ * a good run, and one that never fires is not a cutoff.
+ *
+ * @experimental
+ */
+
+export interface MemoryGuard {
+  readonly ceilingBytes: number
+  readonly windowSamples: number
+  /** Minimum total climb across the window to count as a rise, in bytes. */
+  readonly riseBytes: number
+  samples: number[]
+  tripped: null | 'ceiling' | 'sustained-rise'
+}
+
+/**
+ * 250 MB. Healthy single-clip playback plateaus near 65 MB.
+ *
+ * Was 400 MB, which a 1 MB/s leak takes six minutes to reach — long enough for
+ * a five-minute run to finish, look successful, and leave the process fat
+ * enough that the next run pushed the device into reclaiming from other
+ * applications.
+ */
+export const DEFAULT_CEILING_BYTES = 250 * 1024 * 1024
+
+/** Forty samples at 4 Hz — ten seconds of uninterrupted climbing. */
+export const DEFAULT_WINDOW_SAMPLES = 40
+
+/**
+ * 8 MB across the window: ~0.8 MB/s.
+ *
+ * Was 24 MB over three seconds — 8 MB/s, calibrated against a leak that hit
+ * 1.5 GB in a minute. It was blind to the 1.07 MB/s leak that actually got the
+ * process killed, so the cutoff never fired. A cutoff tuned only to the last
+ * failure is not a cutoff.
+ *
+ * A threshold this small is safe only because the rise must also be *strictly*
+ * increasing at every one of the forty samples. Real memory jitters; a leak
+ * does not.
+ */
+export const DEFAULT_RISE_BYTES = 8 * 1024 * 1024
+
+export function createMemoryGuard(
+  ceilingBytes = DEFAULT_CEILING_BYTES,
+  windowSamples = DEFAULT_WINDOW_SAMPLES,
+  riseBytes = DEFAULT_RISE_BYTES,
+): MemoryGuard {
+  return {
+    ceilingBytes,
+    windowSamples: Math.max(3, Math.floor(windowSamples)),
+    riseBytes,
+    samples: [],
+    tripped: null,
+  }
+}
+
+/**
+ * Record a reading and decide whether to stop.
+ *
+ * Once tripped it stays tripped: the caller has already torn the session down,
+ * and a guard that untrips would invite it to start again into the same leak.
+ */
+export function observeMemory(guard: MemoryGuard, bytes: number): MemoryGuard {
+  if (guard.tripped) return guard
+  if (!Number.isFinite(bytes) || bytes <= 0) return guard
+
+  if (bytes >= guard.ceilingBytes) {
+    return { ...guard, samples: [...guard.samples, bytes].slice(-guard.windowSamples), tripped: 'ceiling' }
+  }
+
+  const samples = [...guard.samples, bytes].slice(-guard.windowSamples)
+  if (samples.length < guard.windowSamples) return { ...guard, samples }
+
+  // **Strictly** increasing across the whole window, and a meaningful total
+  // climb. Both conditions matter, and strictness is the subtle one: allowing
+  // equal consecutive samples made a single large allocation followed by a flat
+  // plateau — a decoder starting up — read as a leak. A leak climbs at every
+  // sample; an allocation climbs once and then stops.
+  let climbing = true
+  for (let i = 1; i < samples.length; i++) {
+    if (samples[i]! <= samples[i - 1]!) {
+      climbing = false
+      break
+    }
+  }
+  const climb = samples[samples.length - 1]! - samples[0]!
+  if (climbing && climb >= guard.riseBytes) {
+    return { ...guard, samples, tripped: 'sustained-rise' }
+  }
+  return { ...guard, samples }
+}
+
+/** A sentence a human can act on, or null while nothing is wrong. */
+export function describeTrip(guard: MemoryGuard): string | null {
+  if (!guard.tripped) return null
+  const mb = (b: number) => (b / (1024 * 1024)).toFixed(0)
+  const latest = guard.samples[guard.samples.length - 1] ?? 0
+  return guard.tripped === 'ceiling'
+    ? `native heap reached ${mb(latest)} MB (ceiling ${mb(guard.ceilingBytes)} MB) — session released`
+    : `native heap rose ${mb(latest - (guard.samples[0] ?? 0))} MB across ${guard.samples.length} samples without plateauing — session released`
+}