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.
Slide	Component	Slide page root container, implemented as a slide-friendly Frame wrapper.
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 editable text object. Templates should provide a stable label; label is optional descriptive metadata.
Line	Component	Trackable line primitive for dividers, rules, timeline marks, and other fixed visual objects.
MediaObject	Component	Trackable media figure wrapper for images, video, or other media regions.
Media	Component	Media content element, usually nested inside MediaObject.
MediaCaption	Component	Caption element. Use Text inside it when the caption should be editable.
ObjectEntity	Component	Low-level editing anchor wrapper component. Developers should generally prefer Text, Line, MediaObject, 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.
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: FixedBox, FrameLayout, FrameProps, SlideProps, SlideMeta, MdxAreaProps, MdxAreaOverflow, PressProps, WorkspaceProps, PageGeometry, PressSource, ObjectEntityProps, ObjectEntityElement, TextProps, LineProps, MediaObjectProps, MediaProps, MediaCaptionProps, BaseFigureProps, MediaFigureProps

See Core Object API for fixed-layout objects, slide templates, and editable object identity rules.

@open-press/core/theme

Theme token module for slide and fixed-layout workspaces. It defines portable colors / fonts / typography tokens and emits CSS variables for theme/default.css.

Export	Kind	Purpose
defineTheme(input)	Function	Normalizes theme input into DefinedOpenPressTheme, including resolved colors, typography, and CSS variables.
themeToCssVariables(theme)	Function	Returns a CSS variable map that can be passed to React style.
themeToCssText(theme, selector?)	Function	Generates CSS text, useful for writing stylesheets or theme previews.
ThemeColorSwatches	Component	Renders theme color swatches.
ThemeTypographyGraph	Component	Renders the typography token graph.
ThemeSpec	Component	Renders a complete theme specimen.

Types: OpenPressThemeInput, ThemeColorInput, ThemeTypographyInput, DefinedOpenPressTheme, DefinedThemeColor, DefinedThemeTypography, ThemeVisualizationProps

See Theme API for details.

@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, npm run openpress:word

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/*).