Public API

This document specifies the official public interface of OpenPress. All exported modules, configuration properties, CSS variables, and HTTP endpoints listed here are protected by Semantic Versioning (SemVer); breaking changes to them will trigger a major version upgrade. Internal implementations not listed (such as deep import paths) may change arbitrarily in minor versions.

@open-press/core

The core module, providing the React runtime infrastructure for the document model.

Export	Kind	Purpose
Press	Component	Entry point, boundary, and property registration for declaring a single document. Must be the default export of press/*/press.tsx.
PressContext	Context	Low-level property access interface. Normal users should interact via physical components.
PRESS_MARKER	Symbol	Compile-time identification token.
Frame	Component	Geometry container for a page or nested area. Required property: frameKey.
FRAME_MARKER	Symbol	Renderer-specific Frame identification token.
FrameContext	Context	Exposes current frame state, supporting the development of custom utilities.
MdxArea	Component	Engine-managed measurement and pagination allocation slot. Required property: chainId.
Text	Component	Unstyled text wrapper layer that can be tracked and inline-edited. Required properties: objectId, label.
ObjectEntity	Component	Low-level editing anchor wrapper component. Developers should generally prefer using Text or Frame.
useSource	Hook	Extracts a specific resolved MDX source object for data-driven interface use.
BaseFigure	Component	Base wrapper component for images/callouts, used for theme derivation.
BaseCallout	Component	Same as above, base callout box.
MediaFigure	Component	Image component that encapsulates the logic to convert local relative paths to public/openpress/media absolute paths.
ImageFigure	Alias	Named alias for MediaFigure.

Types: FrameProps, MdxAreaProps, MdxAreaOverflow, PressProps, WorkspaceProps, PageGeometry, PressSource, ObjectEntityProps, ObjectEntityElement, TextProps, BaseFigureProps, BaseCalloutProps, BaseCalloutKind, MediaFigureProps

@open-press/core/mdx

Data source and MDX processing module.

Export	Kind	Purpose
mdxSource(options)	Function	Encapsulates MDX directory/file discovery settings, generating objects for <Press sources> consumption.

@open-press/core/manuscript

Long-form manuscript and typesetting utility module.

Export	Kind	Purpose
Sections	Component	Automatically traverses source content and instantiates pages.
Chapters	Alias	Semantic alias, behaves identical to Sections.
DefaultSectionPage	Component	The default standardized layout container provided.
Toc, TocArea	Component	Generation engine and content container for automated Table of Contents.

Types: SectionsProps, SectionsPageProps, SectionsOpenerProps, ChaptersProps, TocProps, TocAreaProps, TocPageProps

@open-press/core/numbering

Auto-numbering and localization generation utilities.

• formatCaptionLabel(kind, index, options?): Generates localized figure/table labels (e.g., “Figure 1”, “Table 2”).
• defaultCaptionLocale: System default language mapping table.

Scripts and CLI Tools (@open-press/cli & @open-press/create)

Workspace initialization and CLI entry points:

• Initialize project: npm create @open-press <target> -- --type slides --title "..."
• Add Press: open-press create <slug> --type slides
• Install skills: npx skills add <owner/repo>
• Dev operations: npm run dev, npm run build, npm run preview, npm run typecheck, npm run openpress:pdf

Workspace Config

The sole entry point for project operations and environment configurations is the "openpress" node in package.json.

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

Press Tree Entry Point (press/*/press.tsx)

The discovery target for the engine. Each directory must contain a single default export of <Press> and no other named exports, ensuring declarative consistency and metadata resolution.

CSS Variables Contract

The system uses native CSS variables to inject geometric information into external themes. The naming and semantics of these variables are strictly maintained.

Variable	Source	Purpose
--openpress-page-width, -height	<Press page>	Defines the base physical canvas dimensions.
--openpress-page-aspect-ratio, -height-ratio	Engine	Controls proportional scaling layout of the canvas.
--openpress-page-viewport-scale	Runtime	Records the scale ratio from the Workbench developer’s viewport.
--openpress-page-padding-top, -x, -bottom	Theme Layer	Manages document margins and safe areas.
--openpress-page-body-gap	Theme Layer	Determines the spacing distance between elements inside MdxArea.

System Annotation Markup

Standard data markup written into physical source files by the IDE inspector. Must strictly follow this format: /* @openpress-comment id=<ID> ts=<ISO> hint=<HINT> note=<URL_ENCODED> */

HTTP Dev Endpoints

Endpoints exclusively for development mode (located at /__openpress/*), used by the Workbench and peripheral tools.

Path	HTTP Method	Purpose
/openpress/workspace.json	GET	Fetches the global Workspace manifest.
/openpress/<slug>/document.json	GET	Fetches the complete rendered document JSON artifact for a specific Press.
/__openpress/status	GET	Returns a snapshot of the current deployment and compilation status.
/__openpress/comment	GET, POST, PATCH, DELETE	CRUD operations for comment markers.
/__openpress/search	GET	Provides global search against registered MDX sources.
/__openpress/source-edit	GET, POST	Endpoint for source HMR and inline text replacement operations.
/__openpress/project-asset	POST	Provides interface operations for preview-related assets.
/__openpress/deploy	POST	Triggers the Workspace remote deployment adapter.
/__openpress/local-pdf-export	POST	Builds the document’s PDF export file locally.
/__openpress/local-pdf-file	GET	Returns the locally built physical PDF file.

Internal API Limitations

Internal implementations explicitly excluded from guarantees:

• Deep imports not at the top-level barrel import (e.g., @open-press/core/engine/react/pagination.mjs).
• Any implementation details located in document-model (e.g., the internal ID structure generated by mdx-block:).
• Workbench shell and interface components (e.g., HtmlWorkbench, InlineInspectorLayer).
• Engine CLI command source code (you should use npm run openpress:* instead of accessing engine/commands/*).