日本語 | English

StackNest

紹介ページ: https://shelfsmith.github.io/stacknest/ （画面の写真とダウンロード）

Swift ネイティブ、Apple Silicon 対応の画像ライブラリ（カタログ）マネージャです。オリジナルの Stackroom のライブラリ XML を**取り込む（インポートする）**ことができます。

⚠️ 互換性についての注記: StackNest が対応するのは Stackroom ライブラリ XML のインポート（一方向の読み込み）だけです。StackNest 自身のライブラリ形式（.stacknest）は独自で、Stackroom と相互互換ではありません（Stackroom で開いたり書き戻したりはできません）。また StackNest はカタログソフトで、.stacknest はメタデータと表紙サムネの目録です。画像や本の実体ファイルはライブラリの外（元の場所）に置かれ、StackNest はそのパスを参照します。

Status: アクティブ開発中。ローカルでのブラウズから、別 Mac や iPhone のブラウザへ向けたリモート共有までが動作します（各機能の詳細は下記「主な機能」を参照）。主な柱は次のとおりです。

• ローカル管理（Phase 2.9 まで完了）: ブラウズ / 編集 / 検索、内蔵ビューア、マルチライブラリ、ロック、重複検出、ラベルカスタマイズ、DB 予防保全 / 修復。
• リモート共有 / 閲覧 / 編集（Phase 4）: 共有サーバと Web ブラウザ / Web リーダー、別 Mac からのネイティブクライアント、オフラインダウンロード、リモート閲覧のディスク永続キャッシュ。
• 権限分離: 共有トークンで相手ごとに閲覧 / 編集 / 管理者の権限と見せるライブラリを分けられます。編集トークンならリモートからメタデータ / スタンプ / 表紙を編集でき、管理者トークンならリモート追加 / 削除も可能です。
• 自動化: 監視フォルダの自動取込と、ローカルアクセス（CLI stacknest-cli / MCP mcp-stacknest / OpenAPI + Redoc）による操作に対応します。

これは何か

StackNest は、aroma / aromatics soft が開発した Stackroom 2.1b の書き出す Apple Property List XML ライブラリファイルを読み込み、大規模な画像コレクション （10,000 件以上で動作確認済み）をブラウズし、管理するモダンな macOS ネイティブ体験を提供します。

本プロジェクトは aroma / aromatics soft とは無関係です。Swift でゼロから書かれた 独立実装で、Stackroom のライブラリ XML を取り込めます（互換性の詳細は冒頭の注記を参照）。

なぜこのプロジェクトがあるか

オリジナル Stackroom（最終リリース: 2.1b Build 198、2019年）は x86_64 専用バイナリで、 arm64 ネイティブサポートがありません。Rosetta 2 での動作は継続していますが、長期的には ネイティブ書き直しが必要になります。

aroma 氏（原作者）は 2019 年頃、5ch 新・Mac 板のスレッド（egg.5ch.net/test/read.cgi/mac/1391446507）にて次のように述べています：

ライブラリファイルはただの XML だし、その気があるなら たぶん Swift で 一から作ったほうが早いくらい だと思います。

本プロジェクトはこの明示的な推奨に従っています。オリジナル Stackroom のバイナリ、 ソースコード、アイコン、UI スクリーンショット、Sparkle スタイルのブランディングアセットは 再配布していません。ディスク上のライブラリフォーマットのみを観察から再実装しています。

• aroma 氏のオリジナル Stackroom: https://aromaticsapp.blogspot.com/p/stackroom.html
• aroma 氏のリリースブログ: https://aromaticsapp.blogspot.com/

主な機能

• ライブラリブラウズ: グリッド / リストの 2 ビュー、Browser pane（属性別カラムフィルタ）、Detail pane（メタデータ編集）
• 検索: ツールバーの検索バー + SQLite FTS5 による全文検索（大きくスクロールした状態で絞り込むと、一覧は自動で先頭へ戻る）
• マルチ値フィールド: ジャンル / 作者 / キーワード A / B / C はカンマ区切りで複数値を保持し、Browser pane で個別値ごとに絞り込める
• スマートシェルフ: 条件式（N 条件 × AND/OR × 4 マッチタイプ）で動的にコレクションを構成。Apple Mail 風の条件エディタで、インポートした Stackroom スマートプレイリストも動的評価
• スタンプペイン: ユーザ定義の chip（5 列、消去 / 値 / 新規追加）で複数本に一括属性付与
• 重複検出: 別ディレクトリにある同一内容の本を SHA-256 のバイト一致（およびシリーズ + 巻数の一致）で検出。解決シートで「登録のみ削除」「ファイルもゴミ箱へ」、グループ単位の無視に対応
• ファイルの破損チェック: 蔵書アーカイブが壊れていないかを検査。簡易チェック（存在 / サイズ / 開けるか）と詳細な CRC チェックの 2 段階で、前回は正常だったのに今回破損した本（劣化）を先頭に表示します。いつでも中断でき、途中までの結果は残ります。リモート接続からも実行でき（管理者権限のトークンが必要）、CLI / MCP からも操作できます
• ラベルカスタマイズ: 内容系フィールド（ジャンル / ネタ / キーワード A / B / C）と bookType 6 種をライブラリごとに任意名へ変更でき、全表示箇所（列ヘッダ / ソート / Detail / スタンプ / フィルタ / スマートシェルフ）へ一貫反映
• ビューアキー再割当: 設定 ▸ 内蔵ビューア で内蔵ビューアの全操作を任意キーへ再割当（競合は拒否、行ごと / 全体の既定に戻せる、ヘルプ表は現在の割当を反映）
• 大規模ライブラリ性能: 数千〜数万件規模でソートを最適化（ICU 照合キーの前計算により、リスト更新ごとの再ソートを高速化）
• 内蔵ビューア: 専用ウィンドウ / 全画面で、zip / cbz / cbr / 7z / cbt / tar / フォルダ / 単一画像 / PDF を統一パイプライン表示。フィット、ピンチ / ± ズーム、ドラッグでパン、ゾーンクリック / 矢印 / Space でページ送り、数字キーで位置ジャンプ。見開き表示（本ごとに上書き）、本ごとのページ方向（右→左 / 左→右）、スライドショー、続きから読む、巻末挙動（停止 / 次の巻 / ループ）、前後巻ナビ、全画面で開く、ページ送りの演出（なし / フェード / スライド。EPUB と共通）、操作キーのフル再割当（設定 ▸ 内蔵ビューア）ほか。インスタンス管理で同じ本の重複起動を防止し、設定で本ごとに別ウィンドウも選べる。内蔵 / 外部ビューアは設定で切替（画像と EPUB で別々に選べる）。ページ送りの描画は CPU アーキテクチャ別に最適化（Apple Silicon はフル解像度の遅延デコード、Intel は背景での縮小デコード）し、アーカイブは開いたまま順方向に読み進めるため、ページ数の多い本でも引っかかりません
• EPUB を読む（ベータ）: テキストの EPUB は Mac では専用の窓（縦組み・ルビ・見開き、Home/End で本の最初/最後、文字倍率 +/-/=・位置保存、キーは内蔵ビューアと共通、配色はシステム / ライト / ダーク）。**本全体の進捗（「N / M」とバー）を表示し、途中まで読んだ本は「続きから / 最初から」**を訊く。巻送りは同じ窓の中で差し替え、画像の巻とは画像ビューアと EPUB の窓の間で切り替わる（全画面は切り替え先の設定に従う）。Web リーダーとリモート書庫（別 Mac の StackNest）でも読め、読書位置は三者で共有（Web でも画像 1 枚のページは全画面、続きから / 最初からを選べる）。全ページ画像の EPUB は画像ビューアで開く。綴じ方向は取り込み時に EPUB から本へ反映。ベータ: 混在本の挿絵は見開きにならない、検索・目次なし、レイアウトに違和感が出る EPUB あり
• 表紙編集: 各本の表紙を、アーカイブ内の任意ページ選択（EPUB・PDF も対象）、表示範囲のクロップ、外部画像の D&D（または「外部画像を表紙に設定…」メニュー）で差し替え。見た目（サムネイル）だけの変更で、アーカイブ本体や元ファイルは変更しません。ローカルでもリモート（編集トークン）でも利用でき、サーバ側で表紙が変わればリモートのクライアントも一覧リロード / 再接続で追従。表紙の再生成は 1 冊単位でも実行でき、リンク切れの再指定（再リンク）時には表紙とページ数が自動で更新されます
• ファイル操作: ライブラリへの追加 / 削除、⌫ 削除 / ⌘⌫ ゴミ箱 / ⇧⌘R リネーム / ⌘D ファイル移動、各種確認ダイアログ
• キーボードナビ: グリッド / リストの矢印、Shift+矢印（範囲選択）、⌘↑↓、Home / End、PageUp / Down、Enter で開く
• グリッドサイズ: ライブラリごとに永続化されるサムネイルサイズのスライダー
• パスワードロック: ライブラリごとに SHA-256（salt 付き）でロック設定可能。Touch ID / Apple Watch による生体認証解錠にも対応
• 対応形式: アーカイブは ZIP / CBZ / RAR / CBR / 7z（libarchive 経由）と PDF（PDFKit）、EPUB（ベータ。表紙・メタデータ・閲覧。Mac では Washi の窓で縦組み・ルビ・見開き、Web リーダーでは foliate-js。全ページ画像の EPUB は画像ビューアで開く）、画像は JPEG / PNG / GIF / WebP / HEIC / HEIF / TIFF / AVIF（NSImage 経由）、動画は MP4 / MOV / M4V（表紙のみ。取り込み時に自動でフレームを拾い、右クリックからシーンを選び直せる（選んだ場面はクロップも可）。再生は外部プレイヤー。MKV / WebM / AVI は AVFoundation が開けないため表紙なし）
• 初回起動ウィザード: 初回起動時にページ送り式ウィザードで「本の開き方（内蔵 / 外部ビューア）→（内蔵選択時）ビューア初期設定 → 最初のライブラリ（新規 / 開く / 取り込み）」を設定。設定 ▸ 一般 からいつでも再表示可能
• インポート: 既存 Stackroom ライブラリ XML から SQLite DB へ移行
• 監視フォルダ（自動取込）: 指定フォルダを監視し、置かれたアーカイブ / 画像フォルダを自動でライブラリへ取り込み（フォルダごとの命名プリセット、初回プレビュー、取込要約バナー）。自動分類（bookType）・厚さ閾値・EPUB の題名を使うかはライブラリごとに上書き可能（「StackNest 設定の値に従う」/ 個別指定）。サブフォルダの扱いはフォルダごとに 3 択（取り込まない / 1 冊として取り込む / 中も個別に取り込む）
• リモート共有（サーバ）: ライブラリを HTTP で配信。共有トークンで相手ごとに閲覧 / 編集 / 管理者の権限と見せるライブラリ（scope）を分けたトークンを発行でき、トークン別の QR / URL、NIC 選択 / IPv6、縮小配信、ロック庫の unlock に対応。トークンの発行 / 名称変更 / 再生成 / 無効化はサーバ再起動なしで即時反映。Web ブラウザから閲覧（list / grid、FTS 検索、ソート、ページ送り）でき、Web リーダー（先読み、見開き / 1 頁送り、続きから、読み方向の双方向即時同期、巻末ナビ、PWA アイコン）で読める。ドラッグめくり（指の動きに 1:1 で追従し、離すと慣性で確定）と空間ナビゲーション（一覧へ戻るとスクロール位置と絞り込みを保持）に対応
• ネイティブリモートクライアント: 別 Mac の StackNest から共有サーバへ接続して閲覧と編集ができる。サイドバー / ファセット / フィルタ / グリッド / リスト / 詳細ペインのフルブラウズ、内蔵ビューア、進捗のサーバ同期に対応。RW（編集可）トークンなら詳細ペインで編集でき、メタデータの一括編集、スタンプ、表紙編集、読み方向変更、ラベルカスタマイズをリモートから行える（管理者トークンなら本の削除も可能。R トークンでもレート / 未読は共有評価 / 閲覧状態として編集可）。取り消し / やり直し（⌘Z / ⌘⇧Z）にも対応し、メタデータ編集の取り消しはサーバの編集前値から復元して同時編集を上書きせず、ゴミ箱削除の取り消しはファイルも元の場所へ復元する。複数冊のリモート削除は進捗バー付きで、途中で中止できる
• リモート閲覧のディスク永続キャッシュ: リモートのページ / 表紙を端末にディスク永続キャッシュ（LRU + 可視保護 + TTL）し、再接続 / 再起動後もキャッシュが効く（設定「リモートキャッシュ」で上限 / 保持期間 / 使用量 / クリアを管理）。内蔵ビューアの先読み（前方優先 + スキップストライド、本 1 冊分の全冊先読みトグル）、プログレスバーへのキャッシュ済み範囲の帯表示、サーバ側の表紙変更への追従にも対応
• オフラインダウンロード: リモートの本を選んでローカル保存し、接続なしで一覧と閲覧（続きから）。外部ビューアを選んでいる形式は外部ビューアで開く（動画も。題名のファイル名で渡す）。タイトル画面 / File メニューの「オフライン」から起動。複数選択で一括ダウンロード / 一括削除（リモート庫のグリッド / 一覧の右クリック「オフラインから削除」でも可）
• リモート / オフライン巻送り: 内蔵ビューアの前 / 次の巻がリモート（隣接巻をストリーム、未 DL 可）でもオフライン（DL 済の連続巻）でも動作。読みかけの巻は「続き / 最初」を選択
• ローカルアクセス（CLI / MCP 自動化）: 同梱の stacknest-cli でライブラリをコマンドライン操作（一覧 / 追加 / 削除 / メタ編集 / 棚 CRUD / 監視 / ロック / 取り込み / 再リンク / 重複 / 共有トークン / スタンプ / ラベル / ファイル名の変更〔rename-files・トークン @series @volume @keywordC〕）。**MCP サーバ（mcp-stacknest）**経由で AI エージェントからも操作でき、ローカルエンドポイントは OpenAPI 3.1 + Redoc の API ドキュメント付き

動作環境

• macOS 15 Sequoia 以降（主要ターゲットは macOS 26 Tahoe）
• Apple Silicon ネイティブ（x86_64 向け Universal Binary も生成）
• ソースからビルドするには Xcode 26+
• 表示言語: 日本語・英語（macOS の言語設定に従う。StackNest だけ別の言語にしたいときは システム設定 ▸ 一般 ▸ 言語と地域 ▸ アプリケーション で選ぶ。Web はブラウザの言語、CLI は STACKNEST_LANG=ja|en でも上書きできる）

インストール（リリース版）

リリース版は CI で自己署名（固定 identity）された Universal ビルドを配布します（匿名の自己署名証明書、Apple Developer 公証なし）。GitHub の Releases から StackNest.app（zip）をダウンロードし、/Applications などへ展開してください。identity が固定のため、Full Disk Access などアプリに付与した権限はアップデートをまたいで持続します。

自己署名アプリは Gatekeeper にブロックされるため、初回のみ許可操作が必要です（2 回目以降は通常どおりダブルクリックで起動）。

重要（macOS 15 Sequoia 以降）: macOS 15 以降は「右クリック →『開く』」での Gatekeeper 回避が廃止されました。未署名 / 自己署名アプリは、いったんブロックされたあとにシステム設定から明示的に許可する必要があります。

方法 A（推奨、GUI / macOS 15、26 で確認）

1. StackNest.app を /Applications に置き、ダブルクリックする（「開けません」ダイアログが出るので「完了」）。
2. システム設定 → プライバシーとセキュリティ を開き、下部の「セキュリティ」セクションに表示される 「"StackNest" は…ブロックされました」の右の 「このまま開く」 をクリック。
3. 認証（Touch ID またはログインパスワード）を求められたら入力し、確認ダイアログで再度 「このまま開く」。

方法 B（ターミナル） — quarantine 属性を除去してから起動（システム設定の操作が不要）：

xattr -dr com.apple.quarantine /Applications/StackNest.app

macOS 14 以前では「右クリック →『開く』」でも開けますが、macOS 15 以降では上記の方法 A（システム設定からの許可）または方法 B を使ってください。

⚠️ 自己署名は「正規の開発元」を保証しません（証明書は匿名です）。信頼できる入手元（本リポジトリの Releases）からのみ導入してください。本プロジェクトは Apple Developer 公証を行いません（自己署名配布で確定）。自分でビルドする場合は下記「ビルド」を参照してください。

リポジトリ構成

App/                  -- macOS App ターゲット（xcodegen 経由で生成、xcodeproj は gitignored）
Sources/
  StackroomFormat/    -- Stackroom ライブラリ XML/plist の読み取り（インポート用）
  LibraryStore/       -- SQLite（GRDB）リポジトリ、Migration、FTS5、マルチ値正規化
  ImageCache/         -- サムネイル描画 / キャッシュ
  ArchiveAdapter/     -- libarchive 経由の ZIP / CBZ / RAR / CBR / 7z 読み込み
  EPUBAdapter/        -- EPUB を読む契約（protocol）。外部依存ゼロ。AppCore はこれにしか依存しない
  WashiEPUBAdapter/   -- 上記契約の実装（shunnag/Washi・MIT）。リポジトリで唯一 WashiCore を import する。差し替え可能
  AppCore/            -- アプリレベルのロジック（LibrarySettings, AppPreferences, LibraryLock, エラー型、外部ビューア起動）— テスト容易性のため SwiftUI 非依存
  LibraryServer/      -- 共有サーバ（Hummingbird）、Web UI / リーダー、OpenAPI/Redoc、アクセスティア / グラント
  LibraryServerAPI/   -- サーバ / クライアント共有の DTO
  RemoteClient/       -- ネイティブリモートクライアント（HTTP クライアント、L1/L2 キャッシュ、先読み）
  StackroomImportCLI/ -- インポータ実行ファイル（swift run stackroom-import）
  StackNestCLI/       -- ヘッドレス CLI（stacknest-cli、ローカル / リモート操作）
mcp-stacknest/        -- MCP サーバ（Python、stacknest-cli を包む、AI エージェント連携）
Tests/                -- Swift Testing モジュール（swift-testing）
docs/                 -- アーキテクチャ、設計メモ、smoke checklist

ビルド

初回セットアップ: libarchive のヘッダを取得する

./Scripts/fetch-libarchive-headers.sh

macOS SDK は libarchive の本体（dylib）は提供するが archive.h を提供しないため、 コンパイルにはヘッダを別途用意する必要があります。このスクリプトは、実行時に実際にリンクされる Apple 製 libarchive と同じバージョンのヘッダを上流から取得し、Sources/ArchiveAdapter/Carchive/vendor/ に置きます（gitignore 済み。リポジトリには含まれません）。

未実行でも Homebrew の libarchive があればビルドは通りますが、ヘッダと実行時ライブラリの バージョンがずれます。ずれると「両方に存在するが戻り値が変わった API」で静かに誤動作しうるため、 swift test の LibarchiveVersionTests が失敗して知らせます。

このテストの判定はコンパイル時に焼き付くため、vendor/ を手で書き換えた直後などは 古い判定が残ることがあります（スクリプト経由なら自動で解消されます）。腑に落ちない結果が出たら swift package clean で作り直してください。

SPM ライブラリと CLI

swift build
swift test
swift run stackroom-import --xml "$HOME/Library/Application Support/stackroom/Stackroom Library.xml" --out /tmp/stackroom.sqlite --force

macOS App

xcodeproj は gitignore されているため、まず xcodegen で生成します。

cd App && xcodegen && cd ..
xcodebuild \
  -project App/StackNest.xcodeproj \
  -scheme StackNest \
  -configuration Debug \
  -destination 'platform=macOS' \
  build

Universal Binary（arm64 + x86_64）でのリリースビルド：

xcodebuild \
  -project App/StackNest.xcodeproj \
  -scheme StackNest \
  -configuration Release \
  -derivedDataPath build \
  CODE_SIGN_IDENTITY=- CODE_SIGNING_REQUIRED=NO CODE_SIGNING_ALLOWED=NO \
  ARCHS="arm64 x86_64" ONLY_ACTIVE_ARCH=NO \
  build

xcodegen 実行後は App/StackNest.xcodeproj を Xcode で開くこともできます。

CLI インポータのリファレンスは docs/importer.md を参照してください。

使い方

アプリのビルドまたは xcodebuild の実行後、macOS アプリを起動します：

open ~/Library/Developer/Xcode/DerivedData/StackNest-*/Build/Products/Debug/StackNest.app

初回起動時（新規インストールで設定なし）は初回起動ウィザードが表示され、本の開き方と最初のライブラリを順に設定します。2 回目以降やライブラリ未選択時はタイトル画面が表示され、次の 3 つの選択肢を提示します：

• 新しいライブラリを作成: 任意の場所に空の .stacknest bundle を作成して開く
• 既存のライブラリを開く: 既存の .stacknest bundle を選択して開く
• Stackroom Library から取り込む: aroma 氏のオリジナル Stackroom が出力する Stackroom Library.xml を読み込み、新規 .stacknest bundle として保存

マルチライブラリ対応

各 .stacknest bundle は独立したライブラリ（SQLite DB + assets を含む macOS bundle）で、それぞれ独立した window で同時に開けます。同じライブラリを 2 回開こうとすると既存 window が前面に来ます（OpenLibraryRegistry による二重 open 防止）。

起動モードはアプリ設定（⌘,）の「起動時」で切替可能です：

• タイトル画面を表示（default）
• 前回開いていたライブラリを開く: 終了時に open していた全 library が再度開く
• 指定ライブラリを毎回開く: 設定で指定した特定 library のみ毎回開く

外部ビューアの設定

既定では本は内蔵ビューアで開きます。内蔵 / 外部の切替は画像と EPUB で別々に持てます（設定 ▸ 表示 ▸ ビューア）。動画とテキスト（txt・md・rtf）は内蔵ビューアで開けないため常に外部ビューアで開きます。外部ビューアを使う場合は 設定 ▸ 表示 ▸ 外部ビューア（⌘,）で外部ビューアを設定してください。 「選択…」をクリックして画像ビューアアプリ（cooViewer、Avian、プレビュー 等）を選んでください。種類（画像 / テキスト / 動画）ごとに別のアプリを割り当てられ、EPUB だけさらに別のアプリを指定することもできます（未設定ならデフォルトの設定で開きます）。 設定しない場合、システムの Archive Utility が .zip を展開するだけになります。 選択した外部ビューアは UserDefaults を通じて起動間で保持されます。

設定済みであれば、グリッドで本をダブルクリックするとファイル（またはカバー画像）が 直接選択した外部ビューアで開きます。オフライン（ダウンロード済み）の本も同じ設定に従い、外部ビューアには本の題名のファイル名で渡します。

CLI からのインポート

タイトル画面の「Stackroom Library から取り込む」と同じ DB は、コマンドラインから swift run stackroom-import で生成することもできます（docs/importer.md 参照）。生成された SQLite DB を .stacknest bundle 内に配置して、「既存のライブラリを開く」から開けます。

リモート閲覧（共有、クライアント、オフライン）

StackNest は同じアプリがサーバ（共有）にもクライアントにもなります。別の Mac、iPhone、タブレットのブラウザから、自分のライブラリを閲覧できます。

サーバ側（共有する）

1. 共有したいライブラリを開き、ツールバーのアンテナ（配信インジケータ）または共有設定で共有を ON にします。
2. サーバ設定の共有トークンで、相手ごとに権限（閲覧 / 編集 / 管理者）と見せるライブラリ（scope）を分けたトークンを作り、その URL / QR コード / トークンを接続側へ渡します（NIC 選択、IPv6 対応）。トークンの発行 / 名称変更 / 再生成 / 無効化はサーバ再起動なしで即時反映されます。ロック庫は接続側でパスワード unlock が必要です。
3. セキュリティ: ポートを直接インターネットに公開せず、Tailscale 等の VPN 経由での利用を推奨します（LAN 内利用が前提）。

Web ブラウザから見る

• 接続側のブラウザで共有 URL を開くと、list / grid、全文検索、ソート、ページ送りでブラウズでき、本を開くと Web リーダー（先読み、見開き / 1 頁送り、続きから、読み方向同期）で読めます。テキストの EPUB も読め、画像 1 枚のページは全画面で表示し、本の詳細で「続きから / 最初から」を選べます。

ネイティブクライアント（別 Mac の StackNest から）

• タイトル画面（または File メニュー）の 「サーバに接続…」 から URL とトークンを入力して接続します。サイドバー / ファセット / フィルタ / 詳細ペインのフルブラウズと内蔵ビューアで閲覧でき、読書進捗はサーバへ同期されます。RW（編集可）トークンで接続した場合は、リモートのままメタデータ編集（単一 / 複数一括）、スタンプ、表紙編集（アーカイブ内ページ選択 / クロップ / 外部画像を D&D、「外部画像を表紙に設定…」メニューで表紙に）、読み方向変更ができます（R トークンは読み取り専用）。表紙は見た目のみの変更でアーカイブ本体は不変です。共有元やほかのクライアントで表紙が変わった場合も、一覧リロード / 再接続で追従します。

オフライン（接続なしで読む）

• 接続中に本を右クリック →「ダウンロード」でローカル保存します。「選択」モードで複数選択 → 一括ダウンロードも可能です（シリーズをファセット / 検索で絞って「すべて選択」が便利）。
• タイトル画面 / File メニューの 「オフライン（ダウンロード済み）」 から、サーバに接続していなくてもダウンロード済みの本を一覧と閲覧ができます（続きから、巻送り対応。外部ビューアを選んでいる形式は外部ビューアで開きます）。不要になった本は「選択」モードで一括削除できます（リモート庫のグリッド / 一覧の右クリック「オフラインから削除」でも消せます）。

ローカルアクセス（CLI / MCP による自動化）

StackNest は、GUI を介さずにコマンドラインや AI エージェントからライブラリを操作できます。

• 有効化: アプリ設定（⌘,）の 「一般 ▸ ローカルアクセス」 で有効にします（127.0.0.1 限定のローカル制御エンドポイント）。
• CLI: アプリに同梱の stacknest-cli で、一覧、追加、削除、メタデータ編集、棚 CRUD、監視設定、ロック、取り込み、再リンク、重複スキャン、共有トークン管理、スタンプ / ラベル、ファイルの破損チェック（integrity scan / status / list / full-scan / job-status / cancel）を操作できます（stacknest-cli --help）。パスワードは stdin 入力で argv に露出しません。
• MCP: mcp-stacknest（Model Context Protocol サーバ）を登録すると、対応する AI エージェントから同等の操作ができます。詳細は mcp-stacknest/README.md を参照。
• API ドキュメント: ローカルエンドポイントは API 専用で、ブラウザでルート（/）を開くと Redoc（OpenAPI 3.1） の API リファレンスが表示されます。

ファイルの破損チェック (Phase G27 以降)

蔵書のアーカイブが壊れていないかを検査します。File メニュー ▸ ファイルの破損チェック… で専用ウィンドウが開きます（独立ウィンドウなので、スキャン中も他の操作やアプリの終了を妨げません）。

モード	対象
未検査をスキャン	まだ調べていない本だけ
全件やり直し	すべて調べ直す（数時間〜数十時間かかりうるため開始前に確認）
破損のみ再検査	前回破損と判定された本だけ（ファイルを差し替えた後など）

検査は 2 段階です。簡易チェックはファイルの有無・サイズ・開けるかを見ます。詳細（CRC）チェックはアーカイブ内の各エントリを実際に読んで検証するため確実ですが時間がかかります。いつでも中断でき、途中までの結果は保存されます。

前回は正常だったのに今回破損した本（劣化）は一覧の先頭に表示されます — バックアップから戻すべき本を見つけやすくするためです。

対象は .zip / .cbz / .rar / .cbr / .7z / .cbt / .tar と単独画像です。tar（.cbt / .tar）はデータの CRC を持たないため、詳細チェックでは最後まで読めるかを調べるだけです（コピーが途中で止まって末尾が 0 で埋まった tar は、短いが壊れていない tar として読めます。0 で埋まった .cbt / .tar は破損ではなく「空」と記録されます）。フォルダ・動画・PDF / EPUB は CRC を持たないため「対象外」として記録します（壊れていないという意味ではありません）。設定 ▸ 表示 ▸ 外部ビューア の「拡張子」（「編集…」）で足した拡張子のアーカイブも調べ、StackNest が読めない形式は「対象外」として記録します（0 バイトのファイルは、コピーが途中で止まった残りと見て「破損」と記録します）。

リモート接続からも実行できます。 ただし長時間かかるジョブのため、開始には管理者権限のトークンが必要です（解錠済みかつ admin のときだけメニューが有効になります）。リモートではサーバ機のファイルを指すため「Finder で表示」は使えません。

CLI からは stacknest-cli integrity scan / status / list / full-scan / job-status / cancel で同じ操作ができます。

ライブラリ設定の「データベースを検査」とは別物です。 あちらはライブラリの管理データ（SQLite）を調べるもので、こちらは蔵書ファイルの中身を調べます。

ライブラリのロック (Phase 2.5b 以降)

各 .stacknest ライブラリにはパスワードロックを設定できます。Touch ID / Apple Watch 連携にも対応しています。

ロックが既にある場合、パスワードの変更にも解除にも現在のパスワードが必要です（新規に設定する場合は不要）。解錠したまま席を離れても、第三者がパスワードを書き換えてライブラリを乗っ取ることはできません。この規則は GUI・HTTP・CLI のすべてに適用されます。

パスワードを忘れたとき

リカバリー手段は提供していません。ロックは「簡易的に他者からの偶発的アクセスを防ぐ」目的の機能で、暗号化はされていません。パスワードを忘れて開けなくなったライブラリは、以下の手順で DB を直接編集することで解除 できます。

sqlite3 /path/to/MyLibrary.stacknest/library.sqlite \
  "DELETE FROM library_settings WHERE key IN ('lock_password_hash', 'lock_password_salt', 'lock_use_biometric');"

実行後はロックなし状態になり、StackNest から再度開けるようになります。必要に応じて File menu「このライブラリの設定…」(⇧⌘,) から再設定してください。

注意点:

• ロックは平文 hash + salt の SHA-256 で保護されているのみで、ライブラリ DB / 画像ファイル本体は暗号化されていません
• 強い秘匿性が必要な情報は別の手段 (Disk encryption, FileVault 等) で保護してください

ライブラリの自動バックアップ (Phase 2.8 以降)

クラウド同期下での DB 破損に備え、各 .stacknest ライブラリは編集のあったセッションを閉じるたびに、バンドル内 Backups/ へ世代バックアップ（軽量なメタデータ DB のスナップショット）を自動保存します。閲覧のみで変更がなければ世代は増えません。

• 有効/無効と保持世代数（1〜20、既定 5）はライブラリ設定の「バックアップ」タブで変更できます。
• ライブラリを開くときにデータベースの整合性チェック (PRAGMA quick_check) を行い、破損を検知すると「最新の正常なバックアップから復元しますか？」と案内します（蔵書ファイルの破損チェックとは別物です）。
• バックアップからの復元ができない場合は、続けて**「.recover で修復を試す」**（アプリ内）を選べます。システムの sqlite3 .recover で可能な範囲のデータを救出し、復元できた本の件数を提示してから開きます（壊れた本体は library.prerecover-* / library.corrupt-* として残します）。
• それでも直らない場合や手動で古い世代へ戻したい場合は、DB 復旧ガイド を参照してください（手動 sqlite3 .recover 手順を含む）。

ロードマップ

開発は段階的フェーズで進めています。要約：

フェーズ	内容	状況
2.1	Stackroom XML インポータ（CLI + SQLite/GRDB）	✅ 完了
2.2	グリッド / アイコン表示、サムネイル、アーカイブ読み込み	✅ 完了
2.3	サイドバー（ライブラリ / お気に入り / 最近）、シェルフ、詳細ペイン	✅ 完了
2.4	リスト表示、ツールバー / ファセットフィルタ、FTS5 検索、編集	✅ 完了
2.5	マルチライブラリ、ファイル CRUD、表紙編集、Undo、ロック、命名、自動分類、PDF 取込	✅ 完了
2.5k	グリッド / リストのキーボードナビゲーション	✅ 完了
2.6a	スマートシェルフ MVP（条件式コレクション）	✅ 完了
2.6b	内蔵ビューア コアMVP（フルスクリーン、フィット / ズーム / パン、ページ送り、PDF / アーカイブ / フォルダ / 単一画像）	✅ 完了
2.6b-2	内蔵ビューア拡張（見開き表示、本ごとページ方向、スライドショー自動進行、続きから読む、巻末挙動 次の巻 / ループ、全画面で開く、HEIC / HEIF / TIFF / AVIF 対応）	✅ 完了
2.6c	初回起動ウィザード（内蔵 / 外部ビューア選択、内蔵ビューア初期設定、最初のライブラリ作成、設定から再表示）	✅ 完了
2.7	ブラッシュアップ＆性能（重複検出、フィールド / bookType ラベル カスタマイズ、ソート最適化、ビューアキー再割当 UI、複数命名フォーマットプリセット）	✅ 完了
2.8	ライブラリ保全（リンク切れ再指定、DB 自動バックアップ + 整合性チェック、NFC 正規化修正）	✅ 完了
2.9	DB 修復（アプリ内 .recover による破損データ救出、救出件数提示）	✅ 完了
4.0+	サーバ / クライアント（共有サーバ、Web ブラウザ / リーダー、ネイティブクライアント、オフライン DL、共有トークン［閲覧 / 編集 / 管理者 × scope］、リモート編集［メタ / スタンプ / 表紙: ページ選択、クロップ、外部画像を表紙に / リモート追加、削除 / 取り消し、やり直し（⌘Z / ⌘⇧Z）］、リモート閲覧のディスク永続キャッシュ + 先読み + 表紙キャッシュのサーバ追従、画面サイズに応じた画像配信、監視フォルダ自動取込（設定「取り込み」タブに統合）、内蔵ビューア インスタンス管理（重複起動防止、「複数ビューアの起動を許可」設定）、undo 忠実度（同時編集を上書きしない、ゴミ箱削除の取り消しはファイルも復元）、絞り込み時に一覧が自動で先頭へ、セキュリティ強化（リモート復元経由の任意ファイル移動を防止）、ローカルアクセス（CLI stacknest-cli / MCP mcp-stacknest / OpenAPI + Redoc） — v0.12.0 RC でリモート parity 実装完結。rc.3 で表示性能〔CPU アーキテクチャ別レンダリング、アーカイブの 1 パス読み、Web リーダーのドラッグめくり / 空間ナビ〕とセキュリティ強化を実施）	✅ 完了
4.5	Finder タグとの双方向同期（庫ごとに 1 項目・3 方向マージで削除も伝わる・Spotlight で規模非依存・タグの色を保つ）、内蔵ビューアのルーペ（倍率をスクロールで可変・形と大きさを選択・拡大部分を再デコード） — v0.13.0	✅ 完了
4.6	EPUB 対応（ベータ）（Mac は Washi の窓・Web は foliate-js・リモート書庫とオフラインでも・位置を三者で共有・画像本は画像ビューア・綴じ方向を取り込み時に反映）、メタデータからのファイル名変更を CLI / MCP へ（@series / @volume / @keywordC）、グリッド表示のローカル / リモート統一、列切替で自動スクロール — v0.14.0	✅ 完了
4.7	動画のサムネイル（MP4 / MOV / M4V。取り込み時に自動でフレーム、右クリックからシーンを選び直し、選んだ場面は再生成で再現。リモート / Web の一覧にも表示） — v0.14.3	✅ 完了
4.8	EPUB の操作キーを内蔵ビューアと共通化（同じ割り当て表・再割当が EPUB にも効く／Home・End が本の最初と最後へ／割合ジャンプ・見開き切替・文字倍率・全画面・自動送り・巻移動／EPUB 専用の全画面設定）、オフライン保存のファイル名を元の拡張子に（起動時に既存分も補正）、Washi 1.17.0 — v0.14.4	✅ 完了
4.9	EPUB を読みやすく（本全体の進捗「N / M」とバー・「続きから / 最初から」・巻送りを同じ窓で差し替え・画像ビューアとの切り替え・配色）、ページ送りの演出（なし / フェード / スライド・両ビューア共通）、EPUB 用の外部ビューアとオフラインの外部ビューア対応、設定の「内蔵ビューア」タブ、表紙編集の入口（EPUB・PDF・動画のシーンの切り抜き）と EPUB の題名を取り込みに使う設定、Web リーダーのテキスト EPUB（画像ページを全画面・続きから / 最初から）、Washi 1.21.0 — v0.15.0	✅ 完了
4.10	英語の UI（Mac アプリ・アプリ内ヘルプ・Web・stacknest-cli／MCP。macOS の言語設定に従う。Web はブラウザの言語、CLI は STACKNEST_LANG でも上書き可。--json の出力は言語によらず同じ） — v0.16.0	✅ 完了
4.11	電子書籍の書体と色（和文・欧文の書体・フォントパネル・背景色と文字色のカスタム・同じ文へ戻る）、ホイール／トラックパッドでのページ送り（画像ビューアにも・「スクロールでページを送る」）、内蔵ビューアの設定を 3 節に、対応した外部ビューアとの読書位置の同期（参照ファイル .stacknestbook・リモートの本も中継で）、標準にない拡張子の追加と tar（cbt / tar）、連続した書き込みで一覧が固まる問題の修正、OpenAPI の全操作、Washi 1.24.0 — v0.17.0	✅ 完了
5.0+	ヘッドレス / Docker 対応（共有サーバを StackNest.app に依存せず常時稼働、コンテナ配布、デプロイ / 設定の整備）	⏳ 予定

凡例: ✅ 完了 / 🔄 進行中 / ⏳ 予定 / 🔭 将来構想

Phase 3（安定版リリース儀式）は本プロジェクトの方針に合わないため解体し、アイコン / ブランディング等の達成項目を各 Phase へ吸収しました。

リリースごとの変更点は CHANGELOG.md（English）を参照してください。

フィードバックとコミュニティ

質問、要望、不具合報告、活用例の共有は GitHub Discussions へどうぞ（質問は Q&A、要望は Ideas カテゴリ）。再現手順のあるバグは Issues でも受け付けます。

ライセンス

MIT — LICENSE を参照。

謝辞

• aroma 氏 / aromatics soft — オリジナル Stackroom の開発と、Swift での書き直しへの 明示的な後押しに感謝します。
• Washi（shunnag・MIT）— EPUB の解析と Mac での表示。 画像ページの描画不具合の報告（Issue #1）に迅速に対応いただきました。

使用しているオープンソースソフトウェア

ソフトウェア	用途	ライセンス
Washi	EPUB の解析（WashiCore）と Mac での表示（縦組み・ルビ・見開き・固定レイアウト）	MIT
foliate-js	Web リーダーの EPUB 表示（Sources/LibraryServer/Resources/web/vendor/foliate-js/・コミット固定で vendoring）	MIT
zip.js	Web リーダーで EPUB を展開（同 vendor 配下）	BSD-3-Clause
GRDB.swift	SQLite	MIT
Hummingbird	内蔵サーバ	Apache-2.0
swift-argument-parser	コマンドライン	Apache-2.0
libarchive	ZIP / CBZ / RAR / CBR / 7z の読み込み（macOS 同梱の dylib と上流のヘッダ）	BSD-2-Clause

アプリ内では「StackNest について」（About）の Credits と、ヘルプの「オープンソースと謝辞」に同じ一覧があります。