@agent-native/core 0.86.1 → 0.88.0

package/corpus/templates/clips/desktop/src-tauri/src/native_screen.rs

@@ -158,6 +158,10 @@ struct RestartInfo {
     safe_id: String,
     include_audio: bool,
     capture_system_audio: bool,
+    /// True only when the final media file itself contains microphone audio.
+    /// ScreenCaptureKit microphone muxing is intentionally disabled on macOS
+    /// 15 because SCRecordingOutput can hang finalization and leave no moov.
+    mic_captured_in_file: bool,
     mic_device_id: Option<String>,
     mic_device_label: Option<String>,
     /// Monotonic counter feeding the per-segment filename suffix.
@@ -523,41 +527,66 @@ fn start_native_session_locked(
         || mic_device_label
             .as_deref()
             .is_some_and(|v| !v.trim().is_empty());
-    let session = match start_screencapturekit_recording(
-        app,
-        &safe_id,
-        include_audio,
-        capture_system_audio,
-        mic_device_id.as_deref(),
-        mic_device_label.as_deref(),
-        capture_region,
-        defer_recording_output,
-    ) {
-        Ok(session) => session,
-        Err(sck_err) => {
-            if defer_recording_output {
-                return Err(sck_err);
-            }
-            if include_audio && has_specific_mic {
-                return Err(format!(
-                    "ScreenCaptureKit recording failed before it could use the selected microphone ({sck_err}). Clips did not fall back to macOS screencapture because that would ignore your selected input."
-                ));
-            }
+    let session = if include_audio && !capture_system_audio {
+        if defer_recording_output {
+            return Err(
+                "Skipping microphone-only ScreenCaptureKit warmup; begin will use screencapture."
+                    .to_string(),
+            );
+        }
+        if has_specific_mic {
             eprintln!(
-                "[clips-tray] ScreenCaptureKit recording unavailable; falling back to screencapture: {sck_err}"
+                "[clips-tray] using screencapture for microphone-only recording; selected mic cannot be pinned by this backend"
             );
-            start_screencapture_recording(
-                app,
-                &safe_id,
-                include_audio,
-                capture_system_audio,
-                capture_region,
-            )
-            .map_err(|fallback_err| {
-                format!(
-                    "ScreenCaptureKit recording failed ({sck_err}); screencapture fallback failed ({fallback_err})"
+        } else {
+            eprintln!(
+                "[clips-tray] using screencapture for microphone-only recording to avoid ScreenCaptureKit microphone finalization failures"
+            );
+        }
+        start_screencapture_recording(
+            app,
+            &safe_id,
+            include_audio,
+            capture_system_audio,
+            capture_region,
+        )?
+    } else {
+        match start_screencapturekit_recording(
+            app,
+            &safe_id,
+            include_audio,
+            capture_system_audio,
+            mic_device_id.as_deref(),
+            mic_device_label.as_deref(),
+            capture_region,
+            defer_recording_output,
+        ) {
+            Ok(session) => session,
+            Err(sck_err) => {
+                if defer_recording_output {
+                    return Err(sck_err);
+                }
+                if include_audio && !capture_system_audio && has_specific_mic {
+                    return Err(format!(
+                        "ScreenCaptureKit recording failed before it could use the selected microphone ({sck_err}). Clips did not fall back to macOS screencapture because that would ignore your selected input."
+                    ));
+                }
+                eprintln!(
+                    "[clips-tray] ScreenCaptureKit recording unavailable; falling back to screencapture: {sck_err}"
+                );
+                start_screencapture_recording(
+                    app,
+                    &safe_id,
+                    include_audio,
+                    capture_system_audio,
+                    capture_region,
                 )
-            })?
+                .map_err(|fallback_err| {
+                    format!(
+                        "ScreenCaptureKit recording failed ({sck_err}); screencapture fallback failed ({fallback_err})"
+                    )
+                })?
+            }
         }
     };
     let width = session.width;
@@ -1485,7 +1514,13 @@ pub(crate) fn start_screencapturekit_backend_at(
     } else {
         filter_builder.build()
     };
-    let selected_mic = if include_audio {
+    let capture_microphone_in_recording = false;
+    if include_audio {
+        eprintln!(
+            "[clips-tray] ScreenCaptureKit microphone recording disabled; microphone audio stays out of SCRecordingOutput to avoid macOS 15 finalize timeouts"
+        );
+    }
+    let selected_mic = if capture_microphone_in_recording {
         resolve_microphone_capture_device(mic_device_id, mic_device_label)?
     } else {
         None
@@ -1498,9 +1533,10 @@ pub(crate) fn start_screencapturekit_backend_at(
         .with_queue_depth(8)
         .with_shows_cursor(true)
         // Mic and system audio are independent toggles. SCK delivers them as
-        // separate inputs; SCRecordingOutput muxes them into the file.
+        // separate inputs. We intentionally do not hand microphone buffers to
+        // SCRecordingOutput because macOS 15 can fail to finalize those MP4s.
         .with_captures_audio(capture_system_audio)
-        .with_captures_microphone(include_audio)
+        .with_captures_microphone(capture_microphone_in_recording)
         .with_excludes_current_process_audio(true)
         .with_sample_rate(48000)
         .with_channel_count(2);
@@ -1533,7 +1569,7 @@ pub(crate) fn start_screencapturekit_backend_at(
     let mut stream = SCStream::new(&filter, &config);
     // Observe the microphone stream so `begin` can wait for the first sample
     // before attaching the recording output (avoids the silent-mic head).
-    let mic_ready = if include_audio {
+    let mic_ready = if capture_microphone_in_recording {
         let flag = Arc::new(AtomicBool::new(false));
         let flag_cb = Arc::clone(&flag);
         stream.add_output_handler(
@@ -1559,7 +1595,7 @@ pub(crate) fn start_screencapturekit_backend_at(
         return Err(format!("capture start failed: {err:?}"));
     }
     eprintln!(
-        "[clips-tray] ScreenCaptureKit recording started: {width}x{height} @ {NATIVE_CAPTURE_FPS}fps from {capture_width}x{capture_height} (display {source_width}x{source_height}), mic={include_audio} system_audio={capture_system_audio} deferred_output={defer_recording_output}"
+        "[clips-tray] ScreenCaptureKit recording started: {width}x{height} @ {NATIVE_CAPTURE_FPS}fps from {capture_width}x{capture_height} (display {source_width}x{source_height}), mic_requested={include_audio} mic_recorded={capture_microphone_in_recording} system_audio={capture_system_audio} deferred_output={defer_recording_output}"
     );
     Ok((
         NativeFullscreenBackend::ScreenCaptureKit {
@@ -2180,7 +2216,7 @@ fn saved_recording_from_session(
         height: session.height,
         bytes,
         has_audio,
-        mic_captured: session.restart.include_audio,
+        mic_captured: session.restart.mic_captured_in_file,
         has_camera,
         saved_at: now_iso(),
         last_attempt_at: None,
@@ -2355,6 +2391,7 @@ fn start_screencapturekit_recording(
             safe_id: safe_id.to_string(),
             include_audio,
             capture_system_audio,
+            mic_captured_in_file: false,
             mic_device_id: mic_device_id.map(str::to_string),
             mic_device_label: mic_device_label.map(str::to_string),
             segment_counter: 0,
@@ -2416,6 +2453,7 @@ fn start_screencapture_recording(
             // screencapture (fallback) can't capture system audio; tracked
             // for parity but only `-g` mic is honored by that backend.
             capture_system_audio,
+            mic_captured_in_file: include_audio,
             mic_device_id: None,
             mic_device_label: None,
             segment_counter: 0,
@@ -2717,7 +2755,7 @@ async fn upload_recording_file(
         session.height,
         Some(duration_ms),
         has_audio,
-        session.restart.include_audio,
+        session.restart.mic_captured_in_file,
     )?;
     let upload_result = upload_prepared_recording_file(
         app,

package/corpus/templates/clips/desktop/src-tauri/src/shortcuts.rs

@@ -28,6 +28,7 @@ fn numpad_enter_shortcut() -> Shortcut {
 
 static CUSTOM_VOICE_SHORTCUT: OnceLock<Mutex<Option<Shortcut>>> = OnceLock::new();
 static CUSTOM_POPOVER_SHORTCUT: OnceLock<Mutex<Option<Shortcut>>> = OnceLock::new();
+static CUSTOM_RECORD_SHORTCUT: OnceLock<Mutex<Option<Shortcut>>> = OnceLock::new();
 static FN_TAP_ENABLED: AtomicBool = AtomicBool::new(false);
 static FN_TAP_INSTALL_STARTED: AtomicBool = AtomicBool::new(false);
 static POPOVER_DISMISS_SHORTCUT_ACTIVE: AtomicBool = AtomicBool::new(false);
@@ -41,6 +42,10 @@ fn custom_popover_shortcut() -> &'static Mutex<Option<Shortcut>> {
     CUSTOM_POPOVER_SHORTCUT.get_or_init(|| Mutex::new(None))
 }
 
+fn custom_record_shortcut() -> &'static Mutex<Option<Shortcut>> {
+    CUSTOM_RECORD_SHORTCUT.get_or_init(|| Mutex::new(None))
+}
+
 fn current_custom_voice_shortcut() -> Option<Shortcut> {
     custom_voice_shortcut().lock().ok().and_then(|g| *g)
 }
@@ -49,6 +54,10 @@ fn current_custom_popover_shortcut() -> Option<Shortcut> {
     custom_popover_shortcut().lock().ok().and_then(|g| *g)
 }
 
+fn current_custom_record_shortcut() -> Option<Shortcut> {
+    custom_record_shortcut().lock().ok().and_then(|g| *g)
+}
+
 fn parse_optional_shortcut(value: Option<String>) -> Result<Option<Shortcut>, String> {
     let Some(value) = value else {
         return Ok(None);
@@ -109,21 +118,39 @@ pub async fn set_custom_shortcuts(
     app: AppHandle,
     voice: Option<String>,
     popover: Option<String>,
+    record: Option<String>,
 ) -> Result<(), String> {
     let voice = parse_optional_shortcut(voice)?;
     let popover = parse_optional_shortcut(popover)?;
-    if voice.is_some() && voice == popover {
-        return Err("Voice dictation and Open Clips need different shortcuts.".to_string());
+    let record = parse_optional_shortcut(record)?;
+    if (voice.is_some() && voice == popover)
+        || (voice.is_some() && voice == record)
+        || (popover.is_some() && popover == record)
+    {
+        return Err(
+            "Voice dictation, Open Clips, and Start/stop recording need different shortcuts."
+                .to_string(),
+        );
     }
     let gs = app.global_shortcut();
 
     let prev_voice = swap_custom_shortcut(gs, custom_voice_shortcut(), voice, "voice")?;
-    if let Err(err) = swap_custom_shortcut(gs, custom_popover_shortcut(), popover, "Clips") {
-        // Popover registration failed after voice already mutated — roll the
-        // voice slot back to its previous value so callers see all-or-nothing
-        // behaviour. If the rollback itself fails we surface only the
-        // original popover error to the user; the local state always
-        // reflects whatever actually got registered.
+    let prev_popover = match swap_custom_shortcut(gs, custom_popover_shortcut(), popover, "Clips") {
+        Ok(prev_popover) => prev_popover,
+        Err(err) => {
+            // Popover registration failed after voice already mutated — roll
+            // the voice slot back to its previous value so callers see
+            // all-or-nothing behaviour. If the rollback itself fails we
+            // surface only the original popover error to the user; local
+            // state always reflects whatever actually got registered.
+            let _ = swap_custom_shortcut(gs, custom_voice_shortcut(), prev_voice, "voice");
+            return Err(err);
+        }
+    };
+    if let Err(err) = swap_custom_shortcut(gs, custom_record_shortcut(), record, "recording") {
+        // Recording registration failed after earlier slots already mutated —
+        // roll them back so callers see all-or-nothing behaviour.
+        let _ = swap_custom_shortcut(gs, custom_popover_shortcut(), prev_popover, "Clips");
         let _ = swap_custom_shortcut(gs, custom_voice_shortcut(), prev_voice, "voice");
         return Err(err);
     }
@@ -273,6 +300,9 @@ pub fn build_shortcut_plugin() -> tauri_plugin_global_shortcut::Builder<tauri::W
         let is_custom_popover = current_custom_popover_shortcut()
             .map(|custom| custom == *shortcut)
             .unwrap_or(false);
+        let is_custom_record = current_custom_record_shortcut()
+            .map(|custom| custom == *shortcut)
+            .unwrap_or(false);
         let is_escape = shortcut.matches(Modifiers::empty(), Code::Escape);
         let is_enter = shortcut.matches(Modifiers::empty(), Code::Enter);
         let is_numpad_enter = shortcut.matches(Modifiers::empty(), Code::NumpadEnter);
@@ -347,6 +377,15 @@ pub fn build_shortcut_plugin() -> tauri_plugin_global_shortcut::Builder<tauri::W
         if event.state() != tauri_plugin_global_shortcut::ShortcutState::Pressed {
             return;
         }
+        if is_custom_record {
+            wake_popover_for_recording_shortcut(app);
+            let app = app.clone();
+            thread::spawn(move || {
+                thread::sleep(Duration::from_millis(80));
+                let _ = app.emit("clips:record-shortcut", ());
+            });
+            return;
+        }
         if is_cmd || is_ctrl || is_custom_popover {
             // Loom-style: if a recording is already active, the
             // global shortcut stops it rather than re-opening the
@@ -361,6 +400,19 @@ pub fn build_shortcut_plugin() -> tauri_plugin_global_shortcut::Builder<tauri::W
     })
 }
 
+fn wake_popover_for_recording_shortcut(app: &tauri::AppHandle) {
+    let Some(window) = app.get_webview_window("popover") else {
+        return;
+    };
+    if window.is_visible().unwrap_or(false) {
+        return;
+    }
+    let _ = window.set_position(PhysicalPosition::new(2_i32, 2_i32));
+    let _ = window.set_size(tauri::Size::Physical(PhysicalSize::new(2_u32, 2_u32)));
+    show_without_activation(&window);
+    let _ = app.emit("clips:popover-visible", false);
+}
+
 fn emit_voice_shortcut(
     app: &tauri::AppHandle,
     event: &'static str,

package/corpus/templates/clips/package.json

@@ -20,6 +20,7 @@
   },
   "dependencies": {
     "@agent-native/core": "workspace:*",
+    "@agent-native/toolkit": "workspace:*",
     "@ffmpeg/ffmpeg": "^0.12.15",
     "@ffmpeg/util": "^0.12.2",
     "@fontsource-variable/inter": "^5.2.8",

package/corpus/templates/clips/server/lib/public-agent-context.ts

@@ -2,16 +2,17 @@ import { appStateGet } from "@agent-native/core/application-state";
 import { ssrfSafeFetch } from "@agent-native/core/extensions/url-safety";
 import {
   getSession,
-  signShortLivedToken,
-  verifyShortLivedToken,
+  signScopedAgentAccessToken,
+  verifyScopedAgentAccessToken,
 } from "@agent-native/core/server";
 import { asc, eq } from "drizzle-orm";
 import { getRequestURL, setResponseHeader, type H3Event } from "h3";
 
 import {
-  agentAccessTokenResourceId,
   buildAgentApiUrls,
   buildRecommendedFrames,
+  CLIP_AGENT_ACCESS_TOKEN_PREFIX,
+  CLIPS_AGENT_ACCESS_PARAM,
   CLIP_AGENT_CONTEXT_VERSION,
   toAgentTranscriptSegments,
 } from "../../shared/agent-context.js";
@@ -54,8 +55,8 @@ export type PublicAgentAccessResult =
   | { ok: false; failure: PublicAgentFailure };
 
 const DEFAULT_MAX_AGENT_FRAME_MEDIA_BYTES = 200 * 1024 * 1024;
-export const CLIPS_AGENT_ACCESS_PARAM = "agent_access";
 export const CLIPS_AGENT_ACCESS_TTL_SECONDS = 2 * 60 * 60;
+export { CLIPS_AGENT_ACCESS_PARAM };
 
 function sameOwnerEmail(
   a: string | null | undefined,
@@ -212,10 +213,10 @@ export async function loadPublicAgentAccess(
   );
   const suppliedToken = options.token ?? "";
   const tokenAccess = suppliedToken
-    ? verifyShortLivedToken(
-        suppliedToken,
-        agentAccessTokenResourceId(recording.id),
-      )
+    ? verifyScopedAgentAccessToken(suppliedToken, {
+        resourceKind: CLIP_AGENT_ACCESS_TOKEN_PREFIX,
+        resourceId: recording.id,
+      })
     : null;
   const tokenAllowsAgentAccess = Boolean(tokenAccess?.ok);
 
@@ -252,8 +253,10 @@ export async function loadPublicAgentAccess(
     recording.visibility === "public" &&
     viewerIsOwner
   ) {
-    apiToken = signShortLivedToken({
-      resourceId: agentAccessTokenResourceId(recording.id),
+    apiToken = signScopedAgentAccessToken({
+      resourceKind: CLIP_AGENT_ACCESS_TOKEN_PREFIX,
+      resourceId: recording.id,
+      ttlSeconds: CLIPS_AGENT_ACCESS_TTL_SECONDS,
     });
   }
 
@@ -267,8 +270,10 @@ export async function loadPublicAgentAccess(
       verifySharePassword(suppliedPassword, recording.password)
     ) {
       allowed = true;
-      apiToken = signShortLivedToken({
-        resourceId: agentAccessTokenResourceId(recording.id),
+      apiToken = signScopedAgentAccessToken({
+        resourceKind: CLIP_AGENT_ACCESS_TOKEN_PREFIX,
+        resourceId: recording.id,
+        ttlSeconds: CLIPS_AGENT_ACCESS_TTL_SECONDS,
       });
     }
 

package/corpus/templates/clips/server/lib/recording-media-cleanup.ts

@@ -0,0 +1,110 @@
+import { resolveBuilderCredentials } from "@agent-native/core/server";
+
+import { deleteS3ObjectByUrl } from "./s3-upload-provider.js";
+
+interface RecordingMediaUrls {
+  id?: string;
+  videoUrl?: string | null;
+  thumbnailUrl?: string | null;
+  animatedThumbnailUrl?: string | null;
+}
+
+export interface RecordingMediaCleanupResult {
+  attempted: number;
+  deleted: number;
+  skipped: number;
+  errors: Array<{ url: string; error: string }>;
+}
+
+interface RecordingMediaCleanupOptions {
+  protectedUrls?: Iterable<string>;
+}
+
+export function recordingMediaUrls(recording: RecordingMediaUrls): string[] {
+  const urls = [
+    recording.videoUrl,
+    recording.thumbnailUrl,
+    recording.animatedThumbnailUrl,
+  ];
+  return [...new Set(urls.filter((url): url is string => Boolean(url)))];
+}
+
+function builderAssetUrl(url: string): string | null {
+  try {
+    const parsed = new URL(url);
+    if (parsed.hostname !== "cdn.builder.io") return null;
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    return null;
+  }
+}
+
+async function deleteBuilderAssetByUrl(url: string): Promise<boolean> {
+  const assetUrl = builderAssetUrl(url);
+  if (!assetUrl) return false;
+
+  const credentials = await resolveBuilderCredentials();
+  if (!credentials.privateKey || !credentials.publicKey) return false;
+
+  const deleteUrl = new URL("/api/v1/assets/by-url", "https://cdn.builder.io");
+  deleteUrl.searchParams.set("url", assetUrl);
+  deleteUrl.searchParams.set("apiKey", credentials.publicKey);
+
+  const res = await fetch(deleteUrl.toString(), {
+    method: "DELETE",
+    headers: {
+      Authorization: `Bearer ${credentials.privateKey}`,
+    },
+  });
+
+  if (res.ok) return true;
+  if (res.status === 404) return false;
+
+  const text = await res.text().catch(() => "");
+  throw new Error(
+    `Builder.io asset delete failed (${res.status}): ${text || res.statusText}`,
+  );
+}
+
+export async function deleteRecordingMediaObjects(
+  recording: RecordingMediaUrls,
+  options: RecordingMediaCleanupOptions = {},
+): Promise<RecordingMediaCleanupResult> {
+  const result: RecordingMediaCleanupResult = {
+    attempted: 0,
+    deleted: 0,
+    skipped: 0,
+    errors: [],
+  };
+  const protectedUrls = new Set(options.protectedUrls ?? []);
+
+  for (const url of recordingMediaUrls(recording)) {
+    result.attempted += 1;
+    if (protectedUrls.has(url)) {
+      result.skipped += 1;
+      continue;
+    }
+    try {
+      if (
+        (await deleteS3ObjectByUrl(url)) ||
+        (await deleteBuilderAssetByUrl(url))
+      ) {
+        result.deleted += 1;
+      } else {
+        result.skipped += 1;
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      result.errors.push({ url, error: message });
+      console.warn("[clips] failed to delete recording media object", {
+        recordingId: recording.id,
+        url,
+        error: message,
+      });
+    }
+  }
+
+  return result;
+}

package/corpus/templates/clips/server/lib/s3-upload-provider.ts

@@ -227,6 +227,132 @@ async function putObject(
     : `${cfg.endpoint}/${cfg.bucket}/${key}`;
 }
 
+function withTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value : `${value}/`;
+}
+
+function decodeUrlPathSegment(value: string): string | null {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+}
+
+function keyFromUrlPrefix(rawUrl: URL, rawBase: string): string | null {
+  const base = new URL(withTrailingSlash(rawBase));
+  if (rawUrl.origin !== base.origin) return null;
+  const basePath = withTrailingSlash(base.pathname);
+  if (!rawUrl.pathname.startsWith(basePath)) return null;
+  const encodedKey = rawUrl.pathname.slice(basePath.length);
+  if (!encodedKey) return null;
+  return decodeUrlPathSegment(encodedKey);
+}
+
+function objectKeyFromUrl(cfg: S3Config, rawUrl: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+
+  if (cfg.publicBaseUrl) {
+    const key = keyFromUrlPrefix(url, cfg.publicBaseUrl);
+    if (key) return key;
+  }
+
+  const endpoint = new URL(withTrailingSlash(cfg.endpoint));
+  if (url.origin !== endpoint.origin) return null;
+  const endpointPath = withTrailingSlash(endpoint.pathname);
+  const bucketPath = `${endpointPath}${rfc3986(cfg.bucket)}/`;
+  if (!url.pathname.startsWith(bucketPath)) return null;
+  const encodedKey = url.pathname.slice(bucketPath.length);
+  if (!encodedKey) return null;
+  return decodeUrlPathSegment(encodedKey);
+}
+
+async function deleteObject(cfg: S3Config, key: string): Promise<void> {
+  const now = new Date();
+  const amzDate =
+    now
+      .toISOString()
+      .replace(/[:-]|\.\d{3}/g, "")
+      .slice(0, 15) + "Z";
+  const dateStamp = amzDate.slice(0, 8);
+  const credentialScope = `${dateStamp}/${cfg.region}/s3/aws4_request`;
+
+  const hostUrl = new URL(cfg.endpoint);
+  const host = hostUrl.host;
+  const canonicalUri = `/${cfg.bucket}/${key.split("/").map(rfc3986).join("/")}`;
+  const payloadHash = await sha256(new Uint8Array(0));
+
+  const headers: Record<string, string> = {
+    host,
+    "x-amz-content-sha256": payloadHash,
+    "x-amz-date": amzDate,
+  };
+
+  const signedHeaderKeys = Object.keys(headers).sort();
+  const signedHeaders = signedHeaderKeys.join(";");
+  const canonicalHeaders =
+    signedHeaderKeys.map((k) => `${k}:${headers[k]}`).join("\n") + "\n";
+
+  const canonicalRequest = [
+    "DELETE",
+    canonicalUri,
+    "",
+    canonicalHeaders,
+    signedHeaders,
+    payloadHash,
+  ].join("\n");
+
+  const crHash = await sha256(new TextEncoder().encode(canonicalRequest));
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    amzDate,
+    credentialScope,
+    crHash,
+  ].join("\n");
+
+  const signingKey = await deriveSigningKey(
+    cfg.secretAccessKey,
+    dateStamp,
+    cfg.region,
+  );
+  const signature = toHex(await hmac(signingKey, stringToSign));
+
+  const authorization =
+    `AWS4-HMAC-SHA256 Credential=${cfg.accessKeyId}/${credentialScope}, ` +
+    `SignedHeaders=${signedHeaders}, Signature=${signature}`;
+
+  const url = `${cfg.endpoint}${canonicalUri}`;
+  const res = await fetch(url, {
+    method: "DELETE",
+    headers: {
+      ...headers,
+      Authorization: authorization,
+    },
+  });
+
+  if (!res.ok && res.status !== 404) {
+    const text = await res.text().catch(() => "");
+    throw new Error(
+      `S3 DeleteObject failed (${res.status}): ${text || res.statusText}`,
+    );
+  }
+}
+
+export async function deleteS3ObjectByUrl(url: string): Promise<boolean> {
+  const cfg = await readS3Config();
+  if (!cfg) return false;
+  const key = objectKeyFromUrl(cfg, url);
+  if (!key) return false;
+  await deleteObject(cfg, key);
+  return true;
+}
+
 // ── Provider ──────────────────────────────────────────────────────────
 
 export const s3FileUploadProvider: FileUploadProvider = {