feat: add media save guide

src/components/PopularRankList.tsx

@@ -22,6 +22,7 @@ import { formatDateYmd } from "../utils/format";
 import { postToResource } from "../utils/postResourceAdapter";
 import type { Post } from "../types/post";
 import { downloadAttachment } from "./messageStream/utils/downloadFile";
+import { mediaSaveKindFromType, useSaveToAlbumGuide } from "./SaveToAlbumGuide";
 import { useToast } from "./Toast";
 
 const MEDALS = ["🥇", "🥈", "🥉"];
@@ -94,6 +95,7 @@ function PopularRankRow({
   const navigate = useNavigate();
   const lp = useLocalizedPath();
   const { showToast } = useToast();
+  const { showSaveToAlbumGuide } = useSaveToAlbumGuide();
   const [isDownloading, setIsDownloading] = useState(false);
   const [coverFailed, setCoverFailed] = useState(false);
 
@@ -110,6 +112,8 @@ function PopularRankRow({
         r.downloadAttachmentId,
         r.title,
       );
+      const mediaKind = mediaSaveKindFromType(r.type);
+      if (mediaKind) showSaveToAlbumGuide(mediaKind);
     } catch {
       showToast(t("downloadFail"), "error");
     } finally {

src/components/RecommendedCard.tsx

@@ -13,6 +13,7 @@ import {
   downloadAttachment,
   downloadFile,
 } from "./messageStream/utils/downloadFile";
+import { mediaSaveKindFromType, useSaveToAlbumGuide } from "./SaveToAlbumGuide";
 import { useToast } from "./Toast";
 
 function isPlaceholderAsset(path: string | undefined | null) {
@@ -52,6 +53,7 @@ export function RecommendedCard({
   const { t } = useI18n();
   const lp = useLocalizedPath();
   const { showToast } = useToast();
+  const { showSaveToAlbumGuide } = useSaveToAlbumGuide();
   const [isDownloading, setIsDownloading] = useState(false);
   const figmaCover =
     officialRecommendationCoverFallbacks[
@@ -87,6 +89,8 @@ export function RecommendedCard({
       } else {
         await downloadFile(dl, displayTitle);
       }
+      const mediaKind = mediaSaveKindFromType(r.type);
+      if (mediaKind) showSaveToAlbumGuide(mediaKind);
     } catch {
       showToast(t("downloadFail"), "error");
     } finally {

src/components/SaveToAlbumGuide.tsx

@@ -0,0 +1,185 @@
+import { X } from "lucide-react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+import { useI18n } from "../i18n";
+import type { Attachment } from "../types/post";
+
+export type SaveToAlbumMediaKind = "image" | "video";
+
+type SaveToAlbumGuideContextValue = {
+  showSaveToAlbumGuide: (kind: SaveToAlbumMediaKind) => void;
+};
+
+const SaveToAlbumGuideContext =
+  createContext<SaveToAlbumGuideContextValue | null>(null);
+
+export function useSaveToAlbumGuide(): SaveToAlbumGuideContextValue {
+  const ctx = useContext(SaveToAlbumGuideContext);
+  if (!ctx) {
+    throw new Error(
+      "useSaveToAlbumGuide must be used within SaveToAlbumGuideProvider",
+    );
+  }
+  return ctx;
+}
+
+export function mediaSaveKindFromAttachment(
+  attachment: Attachment,
+): SaveToAlbumMediaKind | null {
+  if (attachment.kind === "image" || attachment.mime.startsWith("image/")) {
+    return "image";
+  }
+  if (attachment.kind === "video" || attachment.mime.startsWith("video/")) {
+    return "video";
+  }
+  return null;
+}
+
+export function mediaSaveKindFromType(
+  type: string | undefined,
+): SaveToAlbumMediaKind | null {
+  if (type === "image") return "image";
+  if (type === "video") return "video";
+  return null;
+}
+
+type SavePlatform = "ios" | "android" | "desktop";
+
+function detectSavePlatform(): SavePlatform {
+  if (typeof navigator === "undefined") return "desktop";
+  const ua = navigator.userAgent || "";
+  if (/android/i.test(ua)) return "android";
+  if (/iPad|iPhone|iPod/i.test(ua)) return "ios";
+  if (navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1) {
+    return "ios";
+  }
+  return "desktop";
+}
+
+function platformStepKeys(platform: SavePlatform): string[] {
+  if (platform === "ios") {
+    return [
+      "saveAlbumGuideIosStep1",
+      "saveAlbumGuideIosStep2",
+      "saveAlbumGuideIosStep3",
+    ];
+  }
+  if (platform === "android") {
+    return [
+      "saveAlbumGuideAndroidStep1",
+      "saveAlbumGuideAndroidStep2",
+      "saveAlbumGuideAndroidStep3",
+    ];
+  }
+  return ["saveAlbumGuideDesktopStep1", "saveAlbumGuideDesktopStep2"];
+}
+
+export function SaveToAlbumGuideProvider({
+  children,
+}: {
+  children: ReactNode;
+}) {
+  const { t } = useI18n();
+  const [mediaKind, setMediaKind] = useState<SaveToAlbumMediaKind | null>(null);
+  const platform = useMemo(() => detectSavePlatform(), []);
+
+  const showSaveToAlbumGuide = useCallback((kind: SaveToAlbumMediaKind) => {
+    setMediaKind(kind);
+  }, []);
+
+  const close = useCallback(() => setMediaKind(null), []);
+
+  useEffect(() => {
+    if (!mediaKind) return;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") close();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [close, mediaKind]);
+
+  const value = useMemo(
+    () => ({ showSaveToAlbumGuide }),
+    [showSaveToAlbumGuide],
+  );
+
+  return (
+    <SaveToAlbumGuideContext.Provider value={value}>
+      {children}
+      {mediaKind
+        ? createPortal(
+            <div
+              className="fixed inset-0 z-[130] flex items-center justify-center bg-black/70 px-4 backdrop-blur-sm"
+              role="dialog"
+              aria-modal="true"
+              aria-labelledby="save-album-guide-title"
+              onClick={close}
+            >
+              <div
+                className="w-full max-w-md overflow-hidden rounded-3xl border border-white/10 bg-[#1c1c21] text-neutral-100 shadow-2xl shadow-black/70"
+                onClick={(event) => event.stopPropagation()}
+              >
+                <div className="flex items-start justify-between gap-4 border-b border-white/10 px-5 py-4">
+                  <div>
+                    <p className="text-xs font-semibold uppercase tracking-[0.2em] text-ark-gold/80">
+                      {mediaKind === "video"
+                        ? t("saveAlbumGuideVideoLabel")
+                        : t("saveAlbumGuideImageLabel")}
+                    </p>
+                    <h2
+                      id="save-album-guide-title"
+                      className="mt-1 text-lg font-semibold text-white"
+                    >
+                      {t("saveAlbumGuideTitle")}
+                    </h2>
+                  </div>
+                  <button
+                    type="button"
+                    onClick={close}
+                    className="flex h-9 w-9 shrink-0 items-center justify-center rounded-full bg-white/10 text-white transition hover:bg-white/20 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ark-gold/80"
+                    aria-label={t("cancel")}
+                  >
+                    <X className="h-5 w-5" />
+                  </button>
+                </div>
+
+                <div className="px-5 py-5">
+                  <p className="text-sm leading-6 text-neutral-300">
+                    {t("saveAlbumGuideIntro")}
+                  </p>
+                  <ol className="mt-4 space-y-3">
+                    {platformStepKeys(platform).map((key, index) => (
+                      <li key={key} className="flex gap-3">
+                        <span className="flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-ark-gold text-sm font-bold text-black">
+                          {index + 1}
+                        </span>
+                        <span className="pt-0.5 text-sm leading-6 text-neutral-100">
+                          {t(key)}
+                        </span>
+                      </li>
+                    ))}
+                  </ol>
+                  <button
+                    type="button"
+                    onClick={close}
+                    className="mt-5 flex h-11 w-full items-center justify-center rounded-full bg-ark-gold px-4 text-sm font-semibold text-black transition hover:bg-ark-gold2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ark-gold/80 focus-visible:ring-offset-2 focus-visible:ring-offset-[#1c1c21]"
+                  >
+                    {t("confirm")}
+                  </button>
+                </div>
+              </div>
+            </div>,
+            document.body,
+          )
+        : null}
+    </SaveToAlbumGuideContext.Provider>
+  );
+}

src/components/messageStream/AttachmentDownloadPill.tsx

@@ -3,8 +3,12 @@ import { DownloadCloudIcon } from "../icons/DownloadCloudIcon";
 import { useState, type MouseEvent } from "react";
 import { useI18n } from "../../i18n";
 import type { Attachment } from "../../types/post";
-import { downloadAttachment } from "./utils/downloadFile";
+import { downloadAttachment, pauseActiveVideos } from "./utils/downloadFile";
 import { formatBytes } from "./utils/formatBytes";
+import {
+  mediaSaveKindFromAttachment,
+  useSaveToAlbumGuide,
+} from "../SaveToAlbumGuide";
 import { useToast } from "../Toast";
 
 type AttachmentDownloadPillProps = {
@@ -40,14 +44,18 @@ export function AttachmentDownloadPill({
 }: AttachmentDownloadPillProps) {
   const { t } = useI18n();
   const { showToast } = useToast();
+  const { showSaveToAlbumGuide } = useSaveToAlbumGuide();
   const [isDownloading, setIsDownloading] = useState(false);
 
   const handleDownload = async (e: MouseEvent<HTMLButtonElement>) => {
     e.stopPropagation();
     if (isDownloading) return;
+    pauseActiveVideos();
     setIsDownloading(true);
     try {
       await downloadAttachment(postId, attachment.id, attachment.filename);
+      const mediaKind = mediaSaveKindFromAttachment(attachment);
+      if (mediaKind) showSaveToAlbumGuide(mediaKind);
     } catch {
       showToast(t("downloadFail"), "error");
     } finally {
@@ -84,6 +92,7 @@ export function AttachmentDownloadPill({
   return (
     <button
       type="button"
+      onPointerDown={(e) => e.stopPropagation()}
       onClick={handleDownload}
       disabled={isDownloading}
       className={`group z-10 inline-flex overflow-hidden rounded-full bg-black/80 ${fontCls} text-white shadow-lg ring-1 ring-inset ring-white/20 backdrop-blur-md transition hover:bg-black/90 disabled:cursor-wait ${className}`}

src/components/messageStream/bubbles/FileDocBubble.tsx

@@ -9,11 +9,16 @@ import { filenameWithExtension, splitFilename } from "../utils/filenameDisplay";
 import { formatBytes } from "../utils/formatBytes";
 import { postDisplayText } from "../utils/postText";
 import { CollapsibleText } from "../CollapsibleText";
+import {
+  mediaSaveKindFromAttachment,
+  useSaveToAlbumGuide,
+} from "../../SaveToAlbumGuide";
 import { useToast } from "../../Toast";
 
 function AttachmentRow({ postId, att }: { postId: string; att: Attachment }) {
   const { t } = useI18n();
   const { showToast } = useToast();
+  const { showSaveToAlbumGuide } = useSaveToAlbumGuide();
   const { Icon, color } = fileIcon({ mime: att.mime, filename: att.filename });
   const displayFilename = filenameWithExtension(att.filename, att.mime);
   const [isDownloading, setIsDownloading] = useState(false);
@@ -24,6 +29,8 @@ function AttachmentRow({ postId, att }: { postId: string; att: Attachment }) {
     setIsDownloading(true);
     try {
       await downloadAttachment(postId, att.id, displayFilename);
+      const mediaKind = mediaSaveKindFromAttachment(att);
+      if (mediaKind) showSaveToAlbumGuide(mediaKind);
     } catch {
       showToast(t("downloadFail"), "error");
     } finally {

src/components/messageStream/bubbles/VideoBubble.tsx

@@ -13,13 +13,14 @@ import {
 import { useVideoPlayer } from "../overlays/VideoPlayer";
 import { autolink } from "../utils/autolink";
 import { CollapsibleText } from "../CollapsibleText";
-import { downloadAttachment } from "../utils/downloadFile";
+import { downloadAttachment, pauseActiveVideos } from "../utils/downloadFile";
 import { formatBytes } from "../utils/formatBytes";
 import { postDisplayText } from "../utils/postText";
 import {
   videoMetadataPreviewSource,
   videoPreviewSource,
 } from "../utils/videoPreviewSource";
+import { useSaveToAlbumGuide } from "../../SaveToAlbumGuide";
 import { useToast } from "../../Toast";
 
 const MAX_VISIBLE = 4;
@@ -167,13 +168,16 @@ function AttachmentListDownloadButton({
 }) {
   const { t } = useI18n();
   const { showToast } = useToast();
+  const { showSaveToAlbumGuide } = useSaveToAlbumGuide();
   const [isDownloading, setIsDownloading] = useState(false);
 
   const handleDownload = async () => {
     if (isDownloading) return;
+    pauseActiveVideos();
     setIsDownloading(true);
     try {
       await downloadAttachment(postId, attachment.id, attachment.filename);
+      showSaveToAlbumGuide("video");
     } catch {
       showToast(t("downloadFail"), "error");
     } finally {
@@ -184,6 +188,7 @@ function AttachmentListDownloadButton({
   return (
     <button
       type="button"
+      onPointerDown={(e) => e.stopPropagation()}
       onClick={(e) => {
         e.stopPropagation();
         handleDownload();

src/components/messageStream/utils/downloadFile.ts

@@ -1,5 +1,11 @@
 import { assetUrl } from "../../../api";
 
+export function pauseActiveVideos() {
+  document.querySelectorAll("video").forEach((video) => {
+    video.pause();
+  });
+}
+
 export function attachmentDownloadUrl(postId: string, attachmentId: string) {
   return assetUrl(
     `/api/posts/${encodeURIComponent(postId)}/attachments/${encodeURIComponent(