公開 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 Tree 進入點 (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 指令原始碼（應使用 npm run openpress:* 而非存取 engine/commands/*）。