@agent-native/core 0.175.0 → 0.175.1

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 8615
+- template files: 8617

package/corpus/templates/assets/app/root.tsx

@@ -146,9 +146,12 @@ export default function Root() {
   useCommandMenuShortcut(useCallback(() => setCmdkOpen(true), []));
   return (
     <AppToolkitProvider>
-      <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+      <AppProviders
+        queryClient={queryClient}
+        toaster={<Toaster richColors position="bottom-left" />}
+        i18n={{ catalog: i18nCatalog }}
+      >
         <DbSyncSetup />
-        <Toaster richColors position="bottom-left" />
         <AssetsCommandMenu open={cmdkOpen} onOpenChange={setCmdkOpen} />
         <AppLayout>
           <Outlet />

package/corpus/templates/clips/actions/create-recording.ts

@@ -172,8 +172,15 @@ export default defineAction({
         );
       } catch (err) {
         if (streamingRequired) {
+          // Keep the underlying reason. A Builder connection that needs
+          // re-authorizing is not fixed by refreshing, and replacing its
+          // message with a retry prompt is why that case looked like a
+          // random failure.
+          const reason = err instanceof Error ? err.message.trim() : "";
           await failUploadSetup(
-            "Video storage could not start a resumable upload session. Refresh and try again.",
+            reason
+              ? `Video storage could not start an upload: ${reason}`
+              : "Video storage could not start a resumable upload session. Refresh and try again.",
           );
         }
         console.warn(

package/corpus/templates/clips/app/components/meetings/share-meeting-dialog.tsx

@@ -262,7 +262,9 @@ function LinkTab({
               ? err.message
               : action === "invite"
                 ? t("clipsFinalRaw.inviteFailed")
-                : t("clipsFinalRaw.removePersonFailed"),
+                : action === "permission"
+                  ? t("clipsFinalRaw.permissionUpdateFailed")
+                  : t("clipsFinalRaw.removePersonFailed"),
           )
         }
       />

package/corpus/templates/clips/app/components/player/share-dialog.tsx

@@ -573,6 +573,17 @@ function LinkTab({
               description: t("shareUi.recordingCommenter.description"),
             },
           }}
+          onError={(err, action) =>
+            toast.error(
+              err instanceof Error
+                ? err.message
+                : action === "invite"
+                  ? t("clipsFinalRaw.inviteFailed")
+                  : action === "permission"
+                    ? t("clipsFinalRaw.permissionUpdateFailed")
+                    : t("clipsFinalRaw.removePersonFailed"),
+            )
+          }
         />
       ) : null}
 

package/corpus/templates/clips/app/components/player/timestamped-comment-button.tsx

@@ -1,6 +1,6 @@
 import { useActionMutation } from "@agent-native/core/client/hooks";
 import { useT } from "@agent-native/core/client/i18n";
-import { IconMessagePlus, IconAt, IconMoodSmile } from "@tabler/icons-react";
+import { IconMessagePlus } from "@tabler/icons-react";
 import { useEffect, useRef, useState } from "react";
 
 import { Button } from "@/components/ui/button";
@@ -74,23 +74,6 @@ export function TimestampedCommentBar({
     requestAnimationFrame(() => textareaRef.current?.focus());
   }, []);
 
-  const insertAtCursor = (text: string) => {
-    const el = textareaRef.current;
-    if (!el) {
-      setDraft(draft + text);
-      return;
-    }
-    const start = el.selectionStart ?? draft.length;
-    const end = el.selectionEnd ?? draft.length;
-    const next = draft.slice(0, start) + text + draft.slice(end);
-    setDraft(next);
-    requestAnimationFrame(() => {
-      el.focus();
-      const pos = start + text.length;
-      el.setSelectionRange(pos, pos);
-    });
-  };
-
   const submit = () => {
     const content = draft.trim();
     if (!content) return;
@@ -130,29 +113,7 @@ export function TimestampedCommentBar({
           rows={2}
           className="min-h-[3rem] resize-none border-0 bg-transparent px-1 text-sm shadow-none focus-visible:ring-0 focus-visible:ring-offset-0"
         />
-        <div className="mt-2 flex items-center justify-between">
-          <div className="flex items-center gap-1">
-            <Button
-              type="button"
-              variant="ghost"
-              size="icon"
-              className="h-8 w-8 text-muted-foreground"
-              aria-label={t("commentsPanel.mentionSomeone")}
-              onClick={() => insertAtCursor("@")}
-            >
-              <IconAt className="h-4 w-4" />
-            </Button>
-            <Button
-              type="button"
-              variant="ghost"
-              size="icon"
-              className="h-8 w-8 text-muted-foreground"
-              aria-label={t("commentsPanel.addEmoji")}
-              onClick={() => insertAtCursor("🙂")}
-            >
-              <IconMoodSmile className="h-4 w-4" />
-            </Button>
-          </div>
+        <div className="mt-2 flex items-center justify-end">
           <div className="flex items-center gap-2">
             <Button type="button" variant="ghost" size="sm" onClick={onClose}>
               {t("common.cancel")}

package/corpus/templates/clips/app/components/sharing/share-ui.tsx

@@ -341,7 +341,7 @@ export function SharePeopleTab({
   sharesQuery: SharesQuery;
   canManage: boolean;
   roleCopy?: Partial<Record<Role, RoleCopy>>;
-  onError?: (err: unknown, action: "invite" | "remove") => void;
+  onError?: (err: unknown, action: "invite" | "permission" | "remove") => void;
 }) {
   const t = useT();
   const share = useActionMutation("share-resource");
@@ -381,6 +381,24 @@ export function SharePeopleTab({
     );
   };
 
+  const handleChangeRole = (s: Share, nextRole: Role) => {
+    if (nextRole === s.role) return;
+    share.mutate(
+      {
+        resourceType,
+        resourceId,
+        principalType: s.principalType,
+        principalId: s.principalId,
+        role: nextRole,
+        notify: false,
+      } as any,
+      {
+        onSuccess: () => sharesQuery.refetch(),
+        onError: (err: unknown) => onError?.(err, "permission"),
+      },
+    );
+  };
+
   const handleRemove = (s: Share) => {
     unshare.mutate(
       {
@@ -476,9 +494,35 @@ export function SharePeopleTab({
             >
               <Avatar label={s.principalId} org={s.principalType === "org"} />
               <span className="flex-1 min-w-0 truncate">{s.principalId}</span>
-              <span className="text-xs text-muted-foreground">
-                {getRoleLabel(s.role)}
-              </span>
+              {canManage ? (
+                <Select
+                  value={s.role}
+                  onValueChange={(value) => handleChangeRole(s, value as Role)}
+                  disabled={share.isPending}
+                >
+                  <SelectTrigger className="h-7 w-[110px] text-xs">
+                    <SelectValue>{getRoleLabel(s.role)}</SelectValue>
+                  </SelectTrigger>
+                  <SelectContent>
+                    {ROLE_OPTIONS.map((opt) => (
+                      <SelectItem key={opt.value} value={opt.value}>
+                        <div className="flex flex-col">
+                          <span>{getRoleLabel(opt.value)}</span>
+                          {getRoleCopy(opt.value)?.description ? (
+                            <span className="text-xs text-muted-foreground">
+                              {getRoleCopy(opt.value)?.description}
+                            </span>
+                          ) : null}
+                        </div>
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              ) : (
+                <span className="text-xs text-muted-foreground">
+                  {getRoleLabel(s.role)}
+                </span>
+              )}
               {canManage ? (
                 <Button
                   type="button"

package/corpus/templates/clips/app/i18n/en-US.ts

@@ -990,8 +990,6 @@ const messages = {
     editComment: "Edit comment",
     commentButton: "Comment",
     composerPlaceholder: "Add a comment…",
-    mentionSomeone: "Mention someone",
-    addEmoji: "Add emoji",
   },
   shareMeeting: {
     pageTitle: "Meeting notes · Clips",
@@ -1528,6 +1526,7 @@ const messages = {
     invite: "Invite",
     inviteFailed: "Couldn't invite person",
     removePersonFailed: "Couldn't remove person",
+    permissionUpdateFailed: "Couldn't update permission",
     passwordProtectedDescription:
       "This video is protected. Enter the password to watch.",
     password: "Password",

package/corpus/templates/clips/app/lib/fmp4-seek.ts

@@ -0,0 +1,274 @@
+/**
+ * Seek policy for the fragmented-MP4 MSE player: given a target time, decide
+ * which byte offset to start appending from.
+ *
+ * Split out from `MseVideoLoader` so the decision-making is pure and testable
+ * without a `MediaSource`. The loader owns the transport (range requests,
+ * source buffer); this owns the one rule that matters:
+ *
+ *   never start appending at a fragment that begins AFTER the seek target.
+ *
+ * MSE does not jump a forward gap, so a fragment that starts even 80ms past the
+ * playhead is not an approximate seek — the element waits for media that will
+ * never be appended, and the viewer sees a spinner forever.
+ *
+ * These recordings are strongly variable-bitrate (a static screen costs almost
+ * nothing, motion costs a lot), so a byte-fraction estimate drifts from the
+ * real timeline by tens of seconds over a long clip, in whichever direction the
+ * earlier part of the clip is quieter or busier than average. The only reliable
+ * answer comes from reading fragment timestamps, which is what this does.
+ */
+
+export interface FragmentLocation {
+  /** Byte offset of the fragment's `moof` box. */
+  byte: number;
+  /** Presentation time the fragment starts at, in seconds. */
+  sec: number;
+}
+
+/** Minimum time span between two anchors used to derive a bitrate. */
+const MIN_SLOPE_SPAN_SECONDS = 0.5;
+
+export interface EstimateBounds {
+  /**
+   * Asset length, or null when it is unknown — cross-origin responses hide
+   * `Content-Range`, so there is no end-of-file anchor to work against.
+   */
+  totalBytes: number | null;
+  durationSec: number;
+}
+
+/**
+ * Observed (byte offset -> fragment start time) pairs, used to interpolate a
+ * probe position. Every probe adds one, so the map sharpens as a viewer scrubs
+ * and later seeks converge in fewer round trips.
+ */
+export class ByteTimeMap {
+  private readonly anchors: FragmentLocation[] = [];
+
+  constructor(private readonly initLength: number) {}
+
+  get size(): number {
+    return this.anchors.length;
+  }
+
+  add(byte: number, sec: number): void {
+    if (!Number.isFinite(byte) || !Number.isFinite(sec)) return;
+    if (byte < this.initLength || sec < 0) return;
+    const existing = this.anchors.findIndex((a) => a.byte === byte);
+    if (existing >= 0) {
+      this.anchors[existing] = { byte, sec };
+      return;
+    }
+    this.anchors.push({ byte, sec });
+    this.anchors.sort((a, b) => a.byte - b.byte);
+  }
+
+  /**
+   * Byte offset to probe for `targetSec`, from the local bitrate around it.
+   *
+   * The two anchors nearest the target in time define the line, whether they
+   * straddle the target or both sit on one side of it. Anchoring on the start
+   * of the file instead — the obvious choice — converges badly here: the line
+   * from t=0 to a point past the target carries the clip's *average* bitrate,
+   * which in a screen recording can be half the local one, so each correction
+   * only covers part of the remaining distance and a seek burns several round
+   * trips walking in.
+   */
+  estimate(targetSec: number, bounds: EstimateBounds): number {
+    const points = this.referencePoints(bounds);
+    const byDistance = points
+      .slice()
+      .sort(
+        (a, b) =>
+          Math.abs(a.sec - targetSec) - Math.abs(b.sec - targetSec) ||
+          a.byte - b.byte,
+      );
+
+    const near = byDistance[0];
+    const far = near
+      ? byDistance.find(
+          (p) =>
+            p.byte !== near.byte &&
+            Math.abs(p.sec - near.sec) >= MIN_SLOPE_SPAN_SECONDS,
+        )
+      : undefined;
+    if (!near || !far) return this.initLength;
+
+    const slope = (far.byte - near.byte) / (far.sec - near.sec);
+    if (!(slope > 0)) return this.initLength;
+    return this.clampByte(near.byte + (targetSec - near.sec) * slope, bounds);
+  }
+
+  /** Anchors plus the two synthetic endpoints, deduplicated by byte offset. */
+  private referencePoints(bounds: EstimateBounds): FragmentLocation[] {
+    const points: FragmentLocation[] = [{ byte: this.initLength, sec: 0 }];
+    for (const anchor of this.anchors) {
+      if (anchor.byte !== this.initLength) points.push(anchor);
+    }
+    if (
+      bounds.totalBytes !== null &&
+      bounds.durationSec > 0 &&
+      bounds.totalBytes > this.initLength &&
+      !points.some((p) => p.byte === bounds.totalBytes)
+    ) {
+      points.push({ byte: bounds.totalBytes, sec: bounds.durationSec });
+    }
+    return points;
+  }
+
+  private clampByte(byte: number, bounds: EstimateBounds): number {
+    const floored = Math.max(this.initLength, Math.floor(byte));
+    if (bounds.totalBytes === null) return floored;
+    return Math.min(floored, Math.max(this.initLength, bounds.totalBytes - 1));
+  }
+}
+
+export interface ResolveSeekOptions<T extends FragmentLocation> {
+  /** Seek target in seconds. */
+  target: number;
+  /** Byte offset of the first media fragment; nothing earlier is probeable. */
+  initLength: number;
+  /** Size of one probe window in bytes. */
+  probeSize: number;
+  /** Probe budget. Bracketed interpolation converges in 2-3 in practice. */
+  maxProbes: number;
+  /**
+   * How far before the target we accept landing. The gap must be downloaded
+   * before playback resumes, so a small number keeps seeks responsive.
+   */
+  acceptUndershootSeconds: number;
+  /** Byte offset to try next, from the anchors learned so far. */
+  estimate: () => number;
+  /** Read the first usable fragment at or after `startByte`, or null. */
+  probe: (startByte: number) => Promise<T | null>;
+  /** Abandon early — a newer seek has superseded this one. */
+  superseded?: () => boolean;
+}
+
+export interface ResolvedSeek<T> {
+  /** Fragment to append from, or null when none could be located. */
+  chosen: T | null;
+  /**
+   * True when `chosen` starts after `target`, so appending it alone leaves the
+   * playhead on an unreachable position and the caller must move the playhead.
+   */
+  overshot: boolean;
+  probes: number;
+  superseded: boolean;
+}
+
+/**
+ * Locate the fragment to start appending from for a seek to `target`.
+ *
+ * Probes, compares the fragment's real start time against the target, and
+ * re-estimates with each new anchor until it lands at or just before the
+ * target, maintaining a byte bracket so every probe makes progress:
+ *
+ *   - `probe` returns the FIRST fragment at or after the position asked for, so
+ *     an overshoot proves no fragment begins in `[probed, fragment)`. The bound
+ *     is therefore the position probed, not the fragment's own offset — that is
+ *     what makes the bracket narrow instead of sitting still while the forward
+ *     scan keeps returning the same fragment.
+ *   - Inside a bracket, the probe goes to whichever is further back: the
+ *     estimate, or a doubling step below the bound. Neither works alone — the
+ *     estimate typically misses by less than one fragment so the bracket only
+ *     creeps, while a blind stride cannot be sized (doubling past one oversized
+ *     fragment walks back to the start of the file). Once a step would pass the
+ *     far end it bisects, and once the bracket is about one window wide it
+ *     probes the floor, the earliest fragment still reachable.
+ *   - With no upper bound yet and an estimate that cannot move (a single
+ *     anchor at t=0, or a duration that understates the clip), the probe
+ *     gallops forward at a doubling stride rather than re-probing one spot
+ *     until the budget is gone.
+ */
+export async function resolveSeekFragment<T extends FragmentLocation>(
+  opts: ResolveSeekOptions<T>,
+): Promise<ResolvedSeek<T>> {
+  const { target, initLength, probeSize, maxProbes } = opts;
+  let landed: T | null = null;
+  let overshoot: T | null = null;
+  /** Highest byte known to hold a fragment at or before `target`. */
+  let lowerByte = initLength;
+  /** Lowest byte known to hold nothing usable at or before `target`. */
+  let upperByte: number | null = null;
+  let forwardStep = probeSize;
+  let backStep = probeSize;
+  let lastStart: number | null = null;
+  let probes = 0;
+
+  for (let attempt = 0; attempt < maxProbes; attempt++) {
+    if (opts.superseded?.()) {
+      return { chosen: null, overshot: false, probes, superseded: true };
+    }
+
+    // Bias slightly early: `probe` scans forward to the next fragment, so
+    // starting a little before the estimated point usually lands under the
+    // target on the first probe instead of the second. The bias is a nudge, not
+    // evidence — the forward-gallop decision below reads the unbiased estimate,
+    // because a bias that dips under the floor must not be mistaken for "the
+    // estimate cannot move forward" and skip an answer sitting at the floor.
+    const estimated = opts.estimate();
+    let guess = estimated - Math.floor(probeSize / 2);
+    if (upperByte !== null) {
+      // Below a known bound, take whichever is further back: the estimate, or a
+      // doubling step. The estimate carries a large correction in one hop, but
+      // on its own it stalls — it typically misses by a fraction of a second,
+      // which is less than one fragment, so the forward scan keeps returning
+      // the same fragment and the bracket creeps. The doubling step guarantees
+      // each probe clears at least one fragment.
+      const ceiling = upperByte - backStep;
+      backStep *= 2;
+      guess = Math.min(guess, ceiling);
+      if (guess <= lowerByte) {
+        // Once the bracket is down to about one window, its floor is the most
+        // informative position left: a forward scan from there returns the
+        // earliest fragment in the bracket. Above that, bisect.
+        guess =
+          upperByte - lowerByte <= probeSize
+            ? lowerByte
+            : Math.floor((lowerByte + upperByte) / 2);
+      }
+    } else if (estimated <= lowerByte) {
+      guess = lowerByte + forwardStep;
+      forwardStep *= 2;
+    }
+
+    const start = Math.max(Math.floor(guess), initLength);
+    if (upperByte !== null && start >= upperByte) break;
+    // No new information is available from a position already probed.
+    if (start === lastStart) break;
+    lastStart = start;
+
+    probes++;
+    const candidate = await opts.probe(start);
+
+    if (!candidate) {
+      // Nothing usable from here to the end of the asset — past EOF, or an
+      // unparseable tail. Bound and keep looking earlier rather than
+      // abandoning the seek, which would strand a viewer whose target is
+      // perfectly playable.
+      if (upperByte === null || start < upperByte) upperByte = start;
+      if (upperByte <= initLength) break;
+      continue;
+    }
+
+    if (candidate.sec <= target) {
+      if (!landed || candidate.sec > landed.sec) landed = candidate;
+      if (candidate.byte > lowerByte) lowerByte = candidate.byte;
+      if (target - candidate.sec <= opts.acceptUndershootSeconds) break;
+      continue; // undershot too far; the fresh anchor sharpens the next guess
+    }
+
+    if (!overshoot || candidate.byte < overshoot.byte) overshoot = candidate;
+    if (upperByte === null || start < upperByte) upperByte = start;
+  }
+
+  const chosen = landed ?? overshoot;
+  return {
+    chosen,
+    overshot: chosen !== null && landed === null,
+    probes,
+    superseded: false,
+  };
+}

package/corpus/templates/clips/app/lib/fmp4.ts

@@ -108,6 +108,174 @@ export interface ParsedInitSegment {
   codecs: string;
   hasVideo: boolean;
   hasAudio: boolean;
+  /** Declared tracks, needed to turn a fragment's `tfdt` into seconds. */
+  tracks: Mp4Track[];
+}
+
+/** Boxes directly contained in `[start, end)`, with offsets relative to `bytes`. */
+function boxesIn(bytes: Uint8Array, start: number, end: number): TopLevelBox[] {
+  const clampedEnd = Math.min(end, bytes.byteLength);
+  if (start >= clampedEnd) return [];
+  return readTopLevelBoxes(bytes.subarray(start, clampedEnd)).map((box) => ({
+    ...box,
+    start: box.start + start,
+  }));
+}
+
+export interface Mp4Track {
+  trackId: number;
+  /** Ticks per second for this track's `tfdt` / `mdhd` timestamps. */
+  timescale: number;
+  /** `hdlr` handler type: "vide", "soun", or "" when absent. */
+  kind: string;
+}
+
+/**
+ * Read each track's id and timescale from a `moov` box (passed including its
+ * own header). A fragment's `tfdt` is in its own track's timescale — Clips
+ * recordings carry video at 600 and audio at 48000 — so converting a fragment
+ * timestamp to seconds without matching its track id is off by 80x.
+ */
+export function parseTracks(moovRegion: Uint8Array): Mp4Track[] {
+  const moovEnd = moovRegion.byteLength;
+  if (moovEnd < 8) return [];
+
+  const tracks: Mp4Track[] = [];
+  for (const trak of boxesIn(moovRegion, 8, moovEnd)) {
+    if (trak.type !== "trak") continue;
+    const trakEnd = trak.size ? trak.start + trak.size : moovEnd;
+    const trakChildren = boxesIn(
+      moovRegion,
+      trak.start + trak.headerSize,
+      trakEnd,
+    );
+    const tkhd = trakChildren.find((b) => b.type === "tkhd");
+    const mdia = trakChildren.find((b) => b.type === "mdia");
+    if (!tkhd || !mdia) continue;
+
+    // FullBox payloads start with a version byte; version 1 widens the two
+    // timestamps that precede the field we want from 4 to 8 bytes each.
+    const trackId = readFullBoxU32(moovRegion, tkhd, 8);
+    if (trackId === null) continue;
+
+    const mdiaEnd = mdia.size ? mdia.start + mdia.size : moovEnd;
+    const mdiaChildren = boxesIn(
+      moovRegion,
+      mdia.start + mdia.headerSize,
+      mdiaEnd,
+    );
+    const mdhd = mdiaChildren.find((b) => b.type === "mdhd");
+    if (!mdhd) continue;
+    const timescale = readFullBoxU32(moovRegion, mdhd, 8);
+    if (timescale === null || timescale <= 0) continue;
+
+    const hdlr = mdiaChildren.find((b) => b.type === "hdlr");
+    let kind = "";
+    if (hdlr) {
+      const handlerAt = hdlr.start + hdlr.headerSize + 8;
+      if (handlerAt + 4 <= moovRegion.byteLength) {
+        kind = readType(moovRegion, handlerAt);
+      }
+    }
+
+    tracks.push({ trackId, timescale, kind });
+  }
+  return tracks;
+}
+
+/**
+ * Read a uint32 from a FullBox payload at `afterTimestamps` bytes past the
+ * version/flags word, accounting for the version-1 widening of the two
+ * timestamp fields that precede it (`tkhd` track_ID, `mdhd` timescale).
+ */
+function readFullBoxU32(
+  bytes: Uint8Array,
+  box: TopLevelBox,
+  afterTimestamps: number,
+): number | null {
+  const payload = box.start + box.headerSize;
+  if (payload >= bytes.byteLength) return null;
+  const version = bytes[payload];
+  const widened = version === 1 ? afterTimestamps * 2 : afterTimestamps;
+  const at = payload + 4 + widened;
+  if (at + 4 > bytes.byteLength) return null;
+  return readU32(bytes, at);
+}
+
+export interface FragmentDecodeTime {
+  /** Track the timestamp belongs to; resolve its timescale via `parseTracks`. */
+  trackId: number;
+  baseMediaDecodeTime: number;
+}
+
+/**
+ * Read the first track fragment's decode time from the `moof` box at
+ * `moofStart`. This is what makes a byte offset locatable on the timeline: it
+ * answers "what presentation time does the fragment at this byte position
+ * start at", which a byte-fraction estimate can only guess at.
+ *
+ * Returns null when the `moof` is truncated or carries no `tfdt`.
+ */
+export function readFragmentDecodeTime(
+  bytes: Uint8Array,
+  moofStart: number,
+): FragmentDecodeTime | null {
+  if (moofStart < 0 || moofStart + 8 > bytes.byteLength) return null;
+  const size = readU32(bytes, moofStart);
+  if (size < 16) return null;
+  const moofEnd = Math.min(moofStart + size, bytes.byteLength);
+
+  for (const traf of boxesIn(bytes, moofStart + 8, moofEnd)) {
+    if (traf.type !== "traf") continue;
+    const trafEnd = traf.size ? traf.start + traf.size : moofEnd;
+    let trackId: number | null = null;
+    let baseMediaDecodeTime: number | null = null;
+
+    for (const child of boxesIn(bytes, traf.start + traf.headerSize, trafEnd)) {
+      const payload = child.start + child.headerSize;
+      if (child.type === "tfhd") {
+        if (payload + 8 <= bytes.byteLength) {
+          trackId = readU32(bytes, payload + 4);
+        }
+      } else if (child.type === "tfdt") {
+        if (payload >= bytes.byteLength) continue;
+        if (bytes[payload] === 1) {
+          if (payload + 12 > bytes.byteLength) continue;
+          // 64-bit: JS numbers hold this exactly for any real recording length.
+          baseMediaDecodeTime =
+            readU32(bytes, payload + 4) * 4294967296 +
+            readU32(bytes, payload + 8);
+        } else {
+          if (payload + 8 > bytes.byteLength) continue;
+          baseMediaDecodeTime = readU32(bytes, payload + 4);
+        }
+      }
+    }
+
+    if (trackId !== null && baseMediaDecodeTime !== null) {
+      return { trackId, baseMediaDecodeTime };
+    }
+  }
+  return null;
+}
+
+/**
+ * Presentation time in seconds of the fragment whose `moof` starts at
+ * `moofStart`, or null when it cannot be read (truncated box, or a track id
+ * absent from `tracks`). Never falls back to a different track's timescale — a
+ * wrong timescale is worse than no answer, because callers use this to decide
+ * where to start appending.
+ */
+export function fragmentPtsSeconds(
+  bytes: Uint8Array,
+  moofStart: number,
+  tracks: readonly Mp4Track[],
+): number | null {
+  const decodeTime = readFragmentDecodeTime(bytes, moofStart);
+  if (!decodeTime) return null;
+  const track = tracks.find((t) => t.trackId === decodeTime.trackId);
+  if (!track || track.timescale <= 0) return null;
+  return decodeTime.baseMediaDecodeTime / track.timescale;
 }
 
 /**
@@ -140,6 +308,7 @@ export function parseInitSegment(bytes: Uint8Array): ParsedInitSegment | null {
     codecs: codecParts.join(","),
     hasVideo,
     hasAudio,
+    tracks: parseTracks(moovRegion),
   };
 }