公開 API

本ドキュメントでは、OpenPressの公式な公開インターフェースについて規定します。ここに記載されているすべてのエクスポートされたモジュール、設定プロパティ、CSS変数、およびHTTPエンドポイントはセマンティックバージョニング (SemVer) によって保護されており、後方互換性のない変更を行うとメジャーバージョンのアップグレードがトリガーされます。記載されていない内部実装（深いインポートパスなど）は、マイナーバージョンで任意に変更される可能性があります。

@open-press/core

原稿モデルのReactランタイムインフラストラクチャを提供するコアモジュール。

エクスポート (Export)	種類 (Kind)	目的 (Purpose)
Press	コンポーネント	単一ドキュメントのエントリポイント、境界、およびプロパティ登録を宣言します。press/*/press.tsx のデフォルトエクスポートである必要があります。
PressContext	Context	低レベルのプロパティアクセスインターフェース。一般ユーザーは実体コンポーネントを介して操作する必要があります。
PRESS_MARKER	Symbol	コンパイル時の識別マーク。
Frame	コンポーネント	ページまたはネストされた領域のジオメトリコンテナ。必須プロパティ：frameKey。
FRAME_MARKER	Symbol	レンダラー専用のFrame識別マーク。
FrameContext	Context	現在のframeの状態を公開し、カスタム補助ツールの開発をサポートします。
MdxArea	コンポーネント	エンジンによって管理される測定とページネーションの割り当てスロット。必須プロパティ：chainId。
Text	コンポーネント	追跡およびインライン編集が可能なスタイルなしのテキストラッパー層。必須プロパティ：objectId、label。
ObjectEntity	コンポーネント	低レベルの編集アンカーラッパーコンポーネント。開発者は通常、Text または Frame を優先して使用する必要があります。
useSource	Hook	データ駆動型インターフェースで使用するために、指定されたMDXソース解決オブジェクトを抽出します。
BaseFigure	コンポーネント	テーマの派生に使用される基本的な画像/コールアウトラッパーコンポーネント。
BaseCallout	コンポーネント	同上、基本的なコールアウトボックス。
MediaFigure	コンポーネント	ローカルの相対パスを public/openpress/media の絶対パスに変換するロジックをカプセル化する画像コンポーネント。
ImageFigure	エイリアス	MediaFigure の名前付きエイリアス。

型定義 (Types): FrameProps, MdxAreaProps, MdxAreaOverflow, PressProps, WorkspaceProps, PageGeometry, PressSource, ObjectEntityProps, ObjectEntityElement, TextProps, BaseFigureProps, BaseCalloutProps, BaseCalloutKind, MediaFigureProps

@open-press/core/mdx

データソースおよびMDX処理モジュール。

エクスポート (Export)	種類 (Kind)	目的 (Purpose)
mdxSource(options)	関数	MDXディレクトリ/ファイルの探索設定をカプセル化し、<Press sources> で消費するためのオブジェクトを生成します。

@open-press/core/manuscript

長編原稿および組版補助ツールモジュール。

エクスポート (Export)	種類 (Kind)	目的 (Purpose)
Sections	コンポーネント	ソースコンテンツを自動的にトラバースし、ページネーションをインスタンス化します。
Chapters	エイリアス	セマンティックエイリアス。動作は Sections と同じです。
DefaultSectionPage	コンポーネント	デフォルトで提供される標準化されたレイアウトコンテナ。
Toc, TocArea	コンポーネント	自動化された目次の生成エンジンおよびコンテンツコンテナ。

型定義 (Types): SectionsProps, SectionsPageProps, SectionsOpenerProps, ChaptersProps, TocProps, TocAreaProps, TocPageProps

@open-press/core/numbering

自動採番とローカリゼーション生成のヘルパー。

• formatCaptionLabel(kind, index, options?): ローカライズされた図表ラベル（「Figure 1」、「表 2」など）を生成します。
• defaultCaptionLocale: システムのデフォルト言語マッピングテーブル。

スクリプトおよびコマンドラインツール (@open-press/cli & @open-press/create)

Workspaceの初期化とCLIの開始点：

• プロジェクトの初期化：npm create @open-press <target> -- --type slides --title "..."
• Pressの追加：open-press create <slug> --type slides
• スキルのインストール：npx skills add <owner/repo>
• 開発操作：npm run dev, npm run build, npm run preview, npm run typecheck, npm run openpress:pdf

操作設定ファイル (Workspace Config)

プロジェクトの操作と環境設定の唯一のエントリポイントは、package.json 内の "openpress" ノードです。

{
  "openpress": {
    "pdf": { "filename": "document.pdf" },
    "deploy": { "adapter": "cloudflare-pages", "projectName": "my-project", "source": ".deploy" }
  }
}

Press ツリーのエントリポイント (press/*/press.tsx)

エンジンの探索ターゲットです。各ディレクトリには唯一のデフォルトエクスポート <Press> が含まれている必要があり、他の名前付きエクスポートは存在してはならず、宣言の一貫性とメタデータの解決が保証されます。

CSS 変数契約 (CSS Variables)

システムはネイティブのCSS変数を使用して外部テーマにジオメトリ情報を注入します。これらの変数の命名とセマンティクスは厳密に維持されます。

変数 (Variable)	コントロールソース (Source)	目的 (Purpose)
--openpress-page-width, -height	<Press page>	ベースキャンバスの物理サイズを定義します。
--openpress-page-aspect-ratio, -height-ratio	エンジン	キャンバスの等比例スケーリングレイアウトを制御します。
--openpress-page-viewport-scale	ランタイム	Workbench 開発者ビューのズーム率を記録します。
--openpress-page-padding-top, -x, -bottom	テーマ層	原稿のマージンとセーフエリアを管理します。
--openpress-page-body-gap	テーマ層	MdxArea 内の要素間の間隔を決定します。

システムアノテーションマークアップ (Annotation Markup)

IDEインスペクターによって物理的なソースファイルに書き込まれる標準データマークアップ。フォーマットは以下に厳密に準拠します： /* @openpress-comment id=<ID> ts=<ISO> hint=<HINT> note=<URL_ENCODED> */

HTTP 開発エンドポイント (Dev Endpoints)

開発モード専用のエンドポイント（/__openpress/* に配置）で、Workbenchおよび周辺ツールセットで使用されます。

パス (Path)	HTTP メソッド	目的 (Purpose)
/openpress/workspace.json	GET	グローバルな Workspace 情報マニフェストを取得します。
/openpress/<slug>/document.json	GET	特定のPressの完全なレンダリングドキュメントJSONアーティファクトを取得します。
/__openpress/status	GET	現在のデプロイおよびコンパイル状態のスナップショットを返します。
/__openpress/comment	GET, POST, PATCH, DELETE	アノテーションマークアップの CRUD 操作。
/__openpress/search	GET	登録済みMDXソースのグローバル検索を提供します。
/__openpress/source-edit	GET, POST	ソースコードのホットリロードとインラインテキスト置換の操作エンドポイント。
/__openpress/project-asset	POST	プレビュー関連のアセットインターフェース操作を提供します。
/__openpress/deploy	POST	Workspace リモートデプロイアダプターをトリガーします。
/__openpress/local-pdf-export	POST	ローカルでドキュメントのPDFエクスポートファイルを構築します。
/__openpress/local-pdf-file	GET	ビルドされたローカルのPDFファイルエンティティを返します。

内部 API 制限事項

保証リストから明示的に除外される内部実装：

• トップレベルの統合インポートポイント (Barrel) にない深いインポート（例：@open-press/core/engine/react/pagination.mjs）。
• document-model にある任意の実装詳細（例：mdx-block: によって生成される内部 ID 構造）。
• Workbench シェルおよびインターフェースコンポーネント（例：HtmlWorkbench, InlineInspectorLayer）。
• エンジンのCLIコマンドソースコード（engine/commands/* にアクセスするのではなく、npm run openpress:* を使用する必要があります）。