@open-press/cli 0.8.0 → 1.1.0

package/template/core/src/openpress/app/OpenPressRuntime.tsx

@@ -1,94 +0,0 @@
-import { useMemo, type CSSProperties } from "react";
-import { PrintDocument, PublicViewer } from "../reader";
-import { isPrintModeLocation, isWorkspaceModeLocation } from "../shared";
-import { HtmlWorkbench } from "../workbench";
-import type {
-  DeploymentInfo,
-  ReaderDocument,
-  HtmlPageBlock,
-  Theme,
-} from "../document-model";
-
-interface OpenPressRuntimeProps {
-  document: ReaderDocument;
-  deploymentInfo?: DeploymentInfo;
-  onDocumentRefresh?: () => void | Promise<void>;
-}
-
-export function OpenPressRuntime({
-  document,
-  deploymentInfo = { online: false },
-  onDocumentRefresh,
-}: OpenPressRuntimeProps) {
-  const style = themeToCssVariables(document.theme);
-  const htmlPages = document.blocks.filter((block): block is HtmlPageBlock => block.kind === "htmlPage");
-  const workspaceMode = useMemo(() => {
-    if (typeof window === "undefined") return false;
-    return isWorkspaceModeLocation(window.location);
-  }, []);
-  const printMode = useMemo(() => {
-    if (typeof window === "undefined") return false;
-    return isPrintModeLocation(window.location);
-  }, []);
-
-  if (htmlPages.length > 0) {
-    if (printMode) {
-      return <PrintDocument document={document} pages={htmlPages} style={style} />;
-    }
-
-    if (!workspaceMode) {
-      return <PublicViewer document={document} pages={htmlPages} style={style} deploymentInfo={deploymentInfo} />;
-    }
-
-    return (
-      <HtmlWorkbench
-        document={document}
-        pages={htmlPages}
-        style={style}
-        devMode={workspaceMode}
-        deploymentInfo={deploymentInfo}
-        onDocumentRefresh={onDocumentRefresh}
-      />
-    );
-  }
-
-  return <EmptyState style={style} workspaceMode={workspaceMode} />;
-}
-
-function EmptyState({ style, workspaceMode }: { style: CSSProperties; workspaceMode: boolean }) {
-  return (
-    <main className="openpress-shell openpress-empty-state" style={style}>
-      <section className="openpress-empty-state__panel">
-        <p className="openpress-empty-state__eyebrow">OpenPress</p>
-        <h1 className="openpress-empty-state__title">This document has no content yet.</h1>
-        <p className="openpress-empty-state__body">
-          Add React MDX chapter files under <code>document/chapters/**/content/</code>, then re-export.
-        </p>
-        {workspaceMode ? (
-          <ol className="openpress-empty-state__steps">
-            <li><code>npm run openpress:export</code> &nbsp;— refreshes <code>public/openpress/document.json</code></li>
-            <li>Reload this page</li>
-          </ol>
-        ) : (
-          <p className="openpress-empty-state__body">
-            (If you are the document author, run <code>npm run dev</code> locally to edit.)
-          </p>
-        )}
-      </section>
-    </main>
-  );
-}
-
-function themeToCssVariables(theme?: Theme) {
-  const style: CSSProperties & Record<`--${string}`, string> = {
-    "--openpress-font-family": theme?.fontFamily ?? "'Noto Sans TC', 'PingFang TC', sans-serif",
-    "--openpress-accent": theme?.accentColor ?? "#df4b21",
-    "--openpress-text": theme?.textColor ?? "#20242a",
-  };
-
-  if (theme?.pageWidth) style["--openpress-page-width"] = theme.pageWidth;
-  if (theme?.pageHeight) style["--openpress-page-height"] = theme.pageHeight;
-  if (theme?.pagePadding) style["--openpress-page-padding"] = theme.pagePadding;
-
-  return style;
-}

package/template/core/src/openpress/app/index.ts

@@ -1,2 +0,0 @@
-export { OpenPressApp } from "./OpenPressApp";
-export { OpenPressRuntime } from "./OpenPressRuntime";

package/template/core/src/openpress/core/Frame.tsx

@@ -1,78 +0,0 @@
-import { useContext } from "react";
-import { cn } from "./cn";
-import { FrameContext, type FrameContextValue } from "./FrameContext";
-import { PressContext } from "./Press";
-import type { FrameProps } from "./types";
-import { createFrameObjectEntityId } from "../document-model/objectEntityModel";
-
-// Substring reserved for the overflow extension pipeline.
-const RESERVED_EXTENDED = ":extended:";
-
-export const FRAME_MARKER: unique symbol = Symbol.for("@open-press/core:Frame");
-
-export function Frame({
-  frameKey,
-  role,
-  chrome = true,
-  className,
-  children,
-  ...rest
-}: FrameProps) {
-  if (!frameKey || !String(frameKey).trim()) {
-    throw new Error("Frame requires a non-empty frameKey.");
-  }
-  if (frameKey && frameKey.includes(RESERVED_EXTENDED)) {
-    throw new Error(
-      `Frame frameKey="${frameKey}" contains reserved substring ":extended:". ` +
-        `This pattern is reserved for the overflow-extension pipeline.`,
-    );
-  }
-
-  const press = useContext(PressContext);
-  const allocation = press?.allocation ?? null;
-  const frameAllocation = frameKey && allocation ? allocation[frameKey] : undefined;
-
-  // Mutable per-render counter. SSR renders a Frame exactly once, so a plain
-  // object is fine — no useRef needed.
-  const areaCounts: Record<string, number> = {};
-  const frameContextValue: FrameContextValue = {
-    frameKey: frameKey ?? "",
-    consumeArea(chainId: string) {
-      const index = areaCounts[chainId] ?? 0;
-      areaCounts[chainId] = index + 1;
-      if (!frameAllocation) return { indexInFrame: index, blocks: null };
-      const chainSlots = frameAllocation[chainId];
-      if (!chainSlots) return { indexInFrame: index, blocks: null };
-      return { indexInFrame: index, blocks: chainSlots[index] ?? null };
-    },
-  };
-
-  const pageKind = derivePageKind(role);
-
-  return (
-    <FrameContext.Provider value={frameContextValue}>
-      <section
-        {...(rest as Record<string, unknown>)}
-        className={cn("reader-page", className)}
-        data-openpress-frame-key={frameKey}
-        data-openpress-object-id={createFrameObjectEntityId(frameKey)}
-        data-frame-role={role}
-        data-page-kind={pageKind}
-        data-frame-chrome={chrome ? "true" : "false"}
-        data-page-footer={chrome ? "true" : "false"}
-      >
-        {children}
-      </section>
-    </FrameContext.Provider>
-  );
-}
-
-(Frame as unknown as { openpressMarker: typeof FRAME_MARKER }).openpressMarker = FRAME_MARKER;
-
-function derivePageKind(role: string | undefined): string | undefined {
-  if (!role) return undefined;
-  const trimmed = role.trim();
-  if (!trimmed) return undefined;
-  const lastDot = trimmed.lastIndexOf(".");
-  return lastDot === -1 ? trimmed : trimmed.slice(lastDot + 1);
-}

package/template/core/src/openpress/core/FrameContext.tsx

@@ -1,24 +0,0 @@
-import { createContext, type ReactNode } from "react";
-
-// FrameContext is the runtime channel between Frame and its descendant
-// MdxArea instances. Frame creates one of these on each render; MdxArea
-// reads it to claim its slot of allocated content.
-//
-// "Claiming" is order-sensitive: the first <MdxArea chainId="X"> rendered
-// inside a Frame takes areaIndex 0 for chain X, the next takes index 1,
-// and so on. Empty Frames (no allocation) return null, which renders the
-// MdxArea as a measurement placeholder.
-
-export interface ConsumedMdxArea {
-  indexInFrame: number;
-  // Null when the frame has no allocation (measurement pass) or no blocks
-  // for this chain at the claimed index.
-  blocks: ReactNode | null;
-}
-
-export interface FrameContextValue {
-  frameKey: string;
-  consumeArea(chainId: string): ConsumedMdxArea;
-}
-
-export const FrameContext = createContext<FrameContextValue | null>(null);

package/template/core/src/openpress/core/MdxArea.tsx

@@ -1,34 +0,0 @@
-import { useContext, type ReactNode } from "react";
-import { cn } from "./cn";
-import { FrameContext } from "./FrameContext";
-import type { MdxAreaProps } from "./types";
-import { createMdxAreaObjectEntityId } from "../document-model/objectEntityModel";
-
-export function MdxArea({
-  chainId,
-  overflow = "extend",
-  className,
-  ...rest
-}: MdxAreaProps) {
-  const frame = useContext(FrameContext);
-  const consumed = frame?.consumeArea(chainId) ?? null;
-  const blocks: ReactNode | null = consumed?.blocks ?? null;
-  const objectId = frame && consumed
-    ? createMdxAreaObjectEntityId(frame.frameKey, chainId, consumed.indexInFrame)
-    : undefined;
-
-  return (
-    <div
-      {...(rest as Record<string, unknown>)}
-      className={cn("openpress-mdx-area", className)}
-      data-openpress-mdx-area="true"
-      data-openpress-mdx-area-chain={chainId}
-      data-openpress-mdx-area-index={consumed?.indexInFrame}
-      data-openpress-object-id={objectId}
-      data-openpress-mdx-area-overflow={overflow}
-      data-openpress-mdx-area-empty={blocks == null ? "true" : "false"}
-    >
-      {blocks}
-    </div>
-  );
-}

package/template/core/src/openpress/core/Press.tsx

@@ -1,34 +0,0 @@
-import { createContext, Fragment, type ReactNode } from "react";
-import type { FrameAllocation, ResolvedSource, TocEntry } from "./types";
-
-// Marker the engine uses to distinguish a Press default export from any other
-// React component. Workspaces register a default export whose `type` is this
-// `Press` component; the engine identity-checks against it.
-export const PRESS_MARKER: unique symbol = Symbol.for("@open-press/core:Press");
-
-// Allocation hints feed Layer 4 results back to Layer 2 so helpers like
-// <Sections> can emit the correct number of pages per chain. Null during
-// the first pass; populated after the allocator has decided how many
-// frames each chain needs.
-export interface AllocationHints {
-  totalPagesPerChain: Record<string, number>;
-}
-
-export interface PressContextValue {
-  sources: Record<string, ResolvedSource>;
-  // Allocation map keyed by frameKey -> chainId -> areaIndex -> blocks.
-  // null during measurement passes; populated during final render.
-  allocation: FrameAllocation | null;
-  // Allocation hints fed back from Layer 4 to Layer 2 helpers. null on
-  // the first measurement pass.
-  hints: AllocationHints | null;
-  toc: Record<string, TocEntry[]> | null;
-}
-
-export const PressContext = createContext<PressContextValue | null>(null);
-
-export function Press({ children }: { children: ReactNode }) {
-  return <Fragment>{children}</Fragment>;
-}
-
-(Press as unknown as { openpressMarker: typeof PRESS_MARKER }).openpressMarker = PRESS_MARKER;

package/template/core/src/openpress/core/cn.ts

@@ -1,4 +0,0 @@
-export function cn(...values: Array<string | false | null | undefined>) {
-  const joined = values.filter(Boolean).join(" ");
-  return joined.length > 0 ? joined : undefined;
-}

package/template/core/src/openpress/core/index.tsx

@@ -1,40 +0,0 @@
-// @open-press/core — Press tree primitives.
-//
-// Layout: this entry exports only the kernel. Source descriptors live in
-// `@open-press/core/mdx`; manuscript helpers live in
-// `@open-press/core/manuscript`. Keeping the surface small is intentional —
-// the engine is not allowed to know about higher-level conventions.
-
-export { Press, PressContext, PRESS_MARKER } from "./Press";
-export { Frame, FRAME_MARKER } from "./Frame";
-export { FrameContext } from "./FrameContext";
-export { MdxArea } from "./MdxArea";
-export { useSource } from "./useSource";
-export { BaseFigure, BaseCallout, MediaFigure, ImageFigure } from "./primitives";
-
-export type {
-  FrameProps,
-  FrameRole,
-  MdxAreaProps,
-  MdxAreaOverflow,
-  PressProps,
-  BaseFigureProps,
-  MediaFigureProps,
-  BaseCalloutKind,
-  BaseCalloutProps,
-  Manifest,
-  // Source-side types are re-exported here for convenience so authors can
-  // import `ResolvedSource` from the same place they import primitives.
-  ResolvedSource,
-  SourceNode,
-  OutlineItem,
-  SourceFileRecord,
-  SourceBlock,
-  TocEntry,
-  MdxSourceDescriptor,
-  SourceDescriptor,
-  FrameAllocation,
-} from "./types";
-
-export type { PressContextValue, AllocationHints } from "./Press";
-export type { FrameContextValue } from "./FrameContext";

package/template/core/src/openpress/core/primitives.tsx

@@ -1,44 +0,0 @@
-import { cn } from "./cn";
-import type { BaseCalloutProps, BaseFigureProps, MediaFigureProps } from "./types";
-
-export function BaseFigure({ caption, className, children, ...figureProps }: BaseFigureProps) {
-  return (
-    <figure {...figureProps} className={cn("openpress-figure", className)}>
-      <div data-figure-body>{children}</div>
-      {caption === undefined ? null : <figcaption>{caption}</figcaption>}
-    </figure>
-  );
-}
-
-export function BaseCallout({ kind = "info", className, children, ...calloutProps }: BaseCalloutProps) {
-  return (
-    <aside {...calloutProps} className={cn("openpress-callout", className)} data-callout-kind={kind}>
-      {children}
-    </aside>
-  );
-}
-
-export function MediaFigure({
-  src,
-  alt,
-  caption,
-  className,
-  imgClassName,
-  loading = "eager",
-  ...figureProps
-}: MediaFigureProps) {
-  return (
-    <BaseFigure {...figureProps} className={cn("openpress-media-figure", className)} caption={caption}>
-      <img src={resolveMediaSrc(src)} alt={alt} loading={loading} className={imgClassName} />
-    </BaseFigure>
-  );
-}
-
-export const ImageFigure = MediaFigure;
-
-function resolveMediaSrc(src: string) {
-  const trimmed = String(src ?? "").trim();
-  if (!trimmed) return "";
-  if (/^(?:[a-z][a-z0-9+.-]*:|\/)/i.test(trimmed)) return trimmed;
-  return `/openpress/media/${trimmed.replace(/^\.?\/*/, "")}`;
-}

package/template/core/src/openpress/core/types.ts

@@ -1,191 +0,0 @@
-import type { HTMLAttributes, ReactNode } from "react";
-
-// ---------------------------------------------------------------------------
-// Frame / MdxArea / Press primitives
-// ---------------------------------------------------------------------------
-
-// `role` is opaque to core. Helpers and themes interpret it; the engine
-// never branches on its value. Format convention is dotted, e.g.
-// "manuscript.cover", "manuscript.content", "folio.page".
-export type FrameRole = string;
-
-export type FrameProps = Omit<HTMLAttributes<HTMLElement>, "role" | "children"> & {
-  frameKey: string;
-  role?: FrameRole;
-  chrome?: boolean;
-  className?: string;
-  children?: ReactNode;
-};
-
-export type MdxAreaOverflow = "extend" | "truncate" | "error";
-
-export type MdxAreaProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
-  chainId: string;
-  overflow?: MdxAreaOverflow;
-  className?: string;
-};
-
-export interface PressProps {
-  children: ReactNode;
-}
-
-// ---------------------------------------------------------------------------
-// Content primitives (figure, callout)
-// ---------------------------------------------------------------------------
-
-export type BaseFigureProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
-  caption?: ReactNode;
-  children: ReactNode;
-};
-
-export type MediaFigureProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
-  src: string;
-  alt: string;
-  caption: ReactNode;
-  imgClassName?: string;
-  loading?: "eager" | "lazy";
-};
-
-export type BaseCalloutKind = "info" | "warn" | "success" | "error" | (string & {});
-
-export type BaseCalloutProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
-  kind?: BaseCalloutKind;
-  children: ReactNode;
-};
-
-// ---------------------------------------------------------------------------
-// Source descriptors and resolved sources
-// ---------------------------------------------------------------------------
-
-export interface MdxSourceDescriptorSectionFolders {
-  type: "mdx";
-  preset: "section-folders";
-  root?: string;
-}
-
-export interface MdxSourceDescriptorSectionFiles {
-  type: "mdx";
-  preset: "section-files";
-  root?: string;
-}
-
-export interface MdxSourceDescriptorFileList {
-  type: "mdx";
-  preset: "file-list";
-  files: string[];
-}
-
-export type MdxSourceDescriptor =
-  | MdxSourceDescriptorSectionFolders
-  | MdxSourceDescriptorSectionFiles
-  | MdxSourceDescriptorFileList;
-
-export type SourceDescriptor = MdxSourceDescriptor;
-
-export interface SourceNode {
-  id: string;
-  slug: string;
-  title: string;
-  meta?: Record<string, unknown>;
-  children?: SourceNode[];
-}
-
-export interface OutlineItem {
-  id: string;
-  depth: number;
-  title: string;
-  sectionSlug: string;
-  pageNumber?: number;
-}
-
-export interface TocEntry {
-  id: string;
-  blockId: string;
-  sourceId: string;
-  sectionSlug: string;
-  title: string;
-  href: string;
-  level: 2 | 3;
-  label: string;
-  pageNumber?: number;
-}
-
-export interface SourceFileRecord {
-  path: string;
-  absolutePath: string;
-  sectionSlug: string;
-}
-
-export interface SourceBlock {
-  id: string;
-  kind: string;
-  name?: string;
-  chainId: string;
-  sectionSlug: string;
-  path: string;
-  source: {
-    file: string;
-    line?: number;
-    column?: number;
-    offset?: number;
-  };
-}
-
-export interface ResolvedSource {
-  id: string;
-  type: "mdx";
-  tree: SourceNode[];
-  outline: OutlineItem[];
-  chains: Record<string, SourceBlock[]>;
-  files: SourceFileRecord[];
-}
-
-// ---------------------------------------------------------------------------
-// Allocation context shape (engine -> Frame -> MdxArea)
-// ---------------------------------------------------------------------------
-
-// Per-frame, per-chain, ordered list of React nodes assigned to each
-// MdxArea by area index.
-export type FrameAllocation = Record<string, Record<string, ReactNode[]>>;
-
-// ---------------------------------------------------------------------------
-// Manifest
-// ---------------------------------------------------------------------------
-
-export interface Manifest {
-  title: string;
-  subtitle?: string;
-  organization?: string;
-  workspaceLabel?: string;
-  documentDir?: string;
-  sourceDir?: string;
-  componentsDir?: string;
-  mediaDir?: string;
-  themeDir?: string;
-  designDoc?: string;
-  publicDir?: string;
-  outputDir?: string;
-  captionNumbering?: {
-    figure?: string;
-    table?: string;
-    separator?: string;
-  };
-  pdf?: {
-    filename?: string;
-  };
-  deploy?: {
-    adapter?: string;
-    source?: string;
-    projectName?: string | null;
-    commitDirty?: boolean;
-    requiresConfirmation?: boolean;
-  };
-  paths?: {
-    chaptersDir?: string;
-    sourceDir?: string;
-    componentsDir?: string;
-    mediaDir?: string;
-    themeDir?: string;
-    designDoc?: string;
-  };
-}

package/template/core/src/openpress/core/useSource.ts

@@ -1,28 +0,0 @@
-import { useContext } from "react";
-import { PressContext } from "./Press";
-import type { ResolvedSource } from "./types";
-
-// Read a resolved source by its registered key. The engine populates the
-// PressContext before rendering, so this is synchronous and safe to call
-// from any component inside <Press>.
-//
-// Throws if the source is missing, with a hint listing known sources.
-export function useSource<T extends ResolvedSource = ResolvedSource>(id: string): T {
-  const ctx = useContext(PressContext);
-  if (!ctx) {
-    throw new Error(
-      `useSource("${id}") called outside <Press> tree. ` +
-        `Source hooks only work inside the default-exported <Press> component.`,
-    );
-  }
-  const source = ctx.sources[id];
-  if (!source) {
-    const known = Object.keys(ctx.sources).sort();
-    const knownText = known.length > 0 ? known.join(", ") : "(none)";
-    throw new Error(
-      `Unknown source "${id}". Available sources: ${knownText}. ` +
-        `Register it under \`export const sources\` in document/index.tsx.`,
-    );
-  }
-  return source as T;
-}

package/template/core/src/openpress/document-model/anchorMapModel.ts

@@ -1,27 +0,0 @@
-// Anchor → page-index resolution shared between the public viewer and
-// the workbench. Lives in its own module so React Fast Refresh can keep
-// `PublicPage` / `HtmlWorkbench` HMR-clean (Fast Refresh expects component
-// files to export only components).
-
-import type { DisplayPage } from "../reader";
-
-export function createAnchorPageMap(pages: DisplayPage[]) {
-  const map = new Map<string, number>();
-  pages.forEach((page, index) => {
-    page.anchors?.forEach((anchor) => {
-      if (anchor && !map.has(anchor)) map.set(anchor, index);
-    });
-  });
-  return map;
-}
-
-export function resolveAnchorPageIndex(
-  anchorPageMap: Map<string, number>,
-  pageCount: number,
-  anchorId: string,
-  pageIndex?: number,
-): number | null {
-  if (typeof pageIndex === "number" && Number.isInteger(pageIndex) && pageIndex >= 0 && pageIndex < pageCount) return pageIndex;
-  const mapped = anchorPageMap.get(anchorId);
-  return mapped === undefined ? null : mapped;
-}