@open-press/core 0.7.0 → 0.8.0

package/src/openpress/{App.tsx → app/OpenPressApp.tsx}

@@ -1,7 +1,7 @@
-import { useEffect, useState } from "react";
-import { Renderer } from "./renderer";
-import { isLocalWorkspaceHost } from "./runtimeMode";
-import type { DeploymentInfo, ReaderDocument } from "./types";
+import { useCallback, useEffect, useState } from "react";
+import { OpenPressRuntime } from "./OpenPressRuntime";
+import { isLocalWorkspaceHost } from "../shared";
+import type { DeploymentInfo, ReaderDocument } from "../document-model";
 
 type LoadState =
   | { status: "loading" }
@@ -39,22 +39,26 @@ function LoadingScreen() {
   );
 }
 
-export function App() {
+export function OpenPressApp() {
   const [state, setState] = useState<LoadState>({ status: "loading" });
 
+  const refreshDocument = useCallback(async () => {
+    const document = await loadReaderDocument();
+    setState((current) => {
+      if (current.status !== "ready") return current;
+      return { ...current, document };
+    });
+  }, []);
+
   useEffect(() => {
     let cancelled = false;
 
     async function loadDocument() {
       try {
-        const [response, deploymentInfo] = await Promise.all([
-          fetch("/openpress/document.json", { cache: "no-store" }),
+        const [document, deploymentInfo] = await Promise.all([
+          loadReaderDocument(),
           loadDeploymentInfo(),
         ]);
-        if (!response.ok) {
-          throw new Error(`Unable to load /openpress/document.json (${response.status})`);
-        }
-        const document = (await response.json()) as ReaderDocument;
         if (!cancelled) {
           setState({ status: "ready", document, deploymentInfo });
         }
@@ -81,13 +85,22 @@ export function App() {
   }
 
   return (
-    <Renderer
+    <OpenPressRuntime
       document={state.document}
       deploymentInfo={state.deploymentInfo}
+      onDocumentRefresh={refreshDocument}
     />
   );
 }
 
+async function loadReaderDocument(): Promise<ReaderDocument> {
+  const response = await fetch("/openpress/document.json", { cache: "no-store" });
+  if (!response.ok) {
+    throw new Error(`Unable to load /openpress/document.json (${response.status})`);
+  }
+  return (await response.json()) as ReaderDocument;
+}
+
 async function loadDeploymentInfo(): Promise<DeploymentInfo> {
   if (typeof window !== "undefined" && isLocalWorkspaceHost(window.location.hostname)) {
     const localInfo = await loadDeploymentInfoFrom("/__openpress/status");

package/src/openpress/{renderer.tsx → app/OpenPressRuntime.tsx}

@@ -1,23 +1,25 @@
 import { useMemo, type CSSProperties } from "react";
-import { PrintDocument, PublicViewer } from "./publicPage";
-import { isPrintModeLocation, isWorkspaceModeLocation } from "./runtimeMode";
-import { HtmlWorkbench } from "./workbench";
+import { PrintDocument, PublicViewer } from "../reader";
+import { isPrintModeLocation, isWorkspaceModeLocation } from "../shared";
+import { HtmlWorkbench } from "../workbench";
 import type {
   DeploymentInfo,
   ReaderDocument,
   HtmlPageBlock,
   Theme,
-} from "./types";
+} from "../document-model";
 
-interface RendererProps {
+interface OpenPressRuntimeProps {
   document: ReaderDocument;
   deploymentInfo?: DeploymentInfo;
+  onDocumentRefresh?: () => void | Promise<void>;
 }
 
-export function Renderer({
+export function OpenPressRuntime({
   document,
   deploymentInfo = { online: false },
-}: RendererProps) {
+  onDocumentRefresh,
+}: OpenPressRuntimeProps) {
   const style = themeToCssVariables(document.theme);
   const htmlPages = document.blocks.filter((block): block is HtmlPageBlock => block.kind === "htmlPage");
   const workspaceMode = useMemo(() => {
@@ -45,6 +47,7 @@ export function Renderer({
         style={style}
         devMode={workspaceMode}
         deploymentInfo={deploymentInfo}
+        onDocumentRefresh={onDocumentRefresh}
       />
     );
   }

package/src/openpress/app/index.ts

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

package/src/openpress/core/Frame.tsx

@@ -1,18 +1,15 @@
-import { useContext, type ReactNode } from "react";
+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");
 
-function classNames(...values: Array<string | undefined>) {
-  const joined = values.filter(Boolean).join(" ");
-  return joined.length > 0 ? joined : undefined;
-}
-
 export function Frame({
   frameKey,
   role,
@@ -40,13 +37,13 @@ export function Frame({
   const areaCounts: Record<string, number> = {};
   const frameContextValue: FrameContextValue = {
     frameKey: frameKey ?? "",
-    consumeArea(chainId: string): ReactNode | null {
+    consumeArea(chainId: string) {
       const index = areaCounts[chainId] ?? 0;
       areaCounts[chainId] = index + 1;
-      if (!frameAllocation) return null;
+      if (!frameAllocation) return { indexInFrame: index, blocks: null };
       const chainSlots = frameAllocation[chainId];
-      if (!chainSlots) return null;
-      return chainSlots[index] ?? null;
+      if (!chainSlots) return { indexInFrame: index, blocks: null };
+      return { indexInFrame: index, blocks: chainSlots[index] ?? null };
     },
   };
 
@@ -56,8 +53,9 @@ export function Frame({
     <FrameContext.Provider value={frameContextValue}>
       <section
         {...(rest as Record<string, unknown>)}
-        className={classNames("reader-page", className)}
+        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"}

package/src/openpress/core/FrameContext.tsx

@@ -9,11 +9,16 @@ import { createContext, type ReactNode } from "react";
 // 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;
-  // Consume the next allocation slot for this chainId. Returns null if the
-  // frame has no allocation (measurement pass) or no blocks for this chain.
-  consumeArea(chainId: string): ReactNode | null;
+  consumeArea(chainId: string): ConsumedMdxArea;
 }
 
 export const FrameContext = createContext<FrameContextValue | null>(null);

package/src/openpress/core/MdxArea.tsx

@@ -1,11 +1,8 @@
 import { useContext, type ReactNode } from "react";
+import { cn } from "./cn";
 import { FrameContext } from "./FrameContext";
 import type { MdxAreaProps } from "./types";
-
-function classNames(...values: Array<string | undefined>) {
-  const joined = values.filter(Boolean).join(" ");
-  return joined.length > 0 ? joined : undefined;
-}
+import { createMdxAreaObjectEntityId } from "../document-model/objectEntityModel";
 
 export function MdxArea({
   chainId,
@@ -14,20 +11,22 @@ export function MdxArea({
   ...rest
 }: MdxAreaProps) {
   const frame = useContext(FrameContext);
-
-  let blocks: ReactNode | null = null;
-  if (frame) {
-    blocks = frame.consumeArea(chainId);
-  }
+  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={classNames("openpress-mdx-area", className)}
+      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" : undefined}
+      data-openpress-mdx-area-empty={blocks == null ? "true" : "false"}
     >
       {blocks}
     </div>

package/src/openpress/core/cn.ts

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

package/src/openpress/core/index.tsx

@@ -10,7 +10,7 @@ export { Frame, FRAME_MARKER } from "./Frame";
 export { FrameContext } from "./FrameContext";
 export { MdxArea } from "./MdxArea";
 export { useSource } from "./useSource";
-export { BaseFigure, BaseCallout } from "./primitives";
+export { BaseFigure, BaseCallout, MediaFigure, ImageFigure } from "./primitives";
 
 export type {
   FrameProps,
@@ -19,6 +19,7 @@ export type {
   MdxAreaOverflow,
   PressProps,
   BaseFigureProps,
+  MediaFigureProps,
   BaseCalloutKind,
   BaseCalloutProps,
   Manifest,

package/src/openpress/core/primitives.tsx

@@ -1,13 +1,9 @@
-import type { BaseCalloutProps, BaseFigureProps } from "./types";
-
-function classNames(...values: Array<string | undefined>) {
-  const joined = values.filter(Boolean).join(" ");
-  return joined.length > 0 ? joined : undefined;
-}
+import { cn } from "./cn";
+import type { BaseCalloutProps, BaseFigureProps, MediaFigureProps } from "./types";
 
 export function BaseFigure({ caption, className, children, ...figureProps }: BaseFigureProps) {
   return (
-    <figure {...figureProps} className={classNames("openpress-figure", className)}>
+    <figure {...figureProps} className={cn("openpress-figure", className)}>
       <div data-figure-body>{children}</div>
       {caption === undefined ? null : <figcaption>{caption}</figcaption>}
     </figure>
@@ -16,8 +12,33 @@ export function BaseFigure({ caption, className, children, ...figureProps }: Bas
 
 export function BaseCallout({ kind = "info", className, children, ...calloutProps }: BaseCalloutProps) {
   return (
-    <aside {...calloutProps} className={classNames("openpress-callout", className)} data-callout-kind={kind}>
+    <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/src/openpress/core/types.ts

@@ -38,6 +38,14 @@ export type BaseFigureProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
   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"> & {

package/src/openpress/{anchorMap.ts → document-model/anchorMapModel.ts}

@@ -3,7 +3,7 @@
 // `PublicPage` / `HtmlWorkbench` HMR-clean (Fast Refresh expects component
 // files to export only components).
 
-import type { DisplayPage } from "./workbenchTypes";
+import type { DisplayPage } from "../reader";
 
 export function createAnchorPageMap(pages: DisplayPage[]) {
   const map = new Map<string, number>();

package/src/openpress/{indexes.ts → document-model/documentIndexes.ts}

@@ -1,4 +1,4 @@
-import type { BlockSource } from "./types";
+import type { BlockSource } from "./documentTypes";
 
 export type MediaAssetKind = "image" | "svg";
 

package/src/openpress/{types.ts → document-model/documentTypes.ts}

@@ -25,6 +25,7 @@ export interface DocumentSource {
   editMode?: string;
   styles?: DocumentStyle[];
   blockMap?: Record<string, SourceBlock>;
+  objectEntities?: Record<string, ObjectEntity>;
 }
 
 export interface DocumentStyle {
@@ -49,6 +50,9 @@ export interface SourceBlock {
   pageIndex?: number;
   pageNumber?: number;
   source?: SourceLocation;
+  frameKey?: string;
+  chainId?: string;
+  sectionSlug?: string;
 }
 
 export interface DocumentMeta {
@@ -93,4 +97,42 @@ export interface HtmlPageBlock {
   anchors?: string[];
   className?: string;
   source?: BlockSource;
+  frameKey?: string;
+  role?: string | null;
+  chrome?: boolean;
+  blockIds?: string[];
+}
+
+export type ObjectEntityKind =
+  | "page"
+  | "frame"
+  | "mdx-area"
+  | "mdx-block"
+  | "component"
+  | "media";
+
+export interface EditableSourceRef {
+  path: string;
+  file?: string;
+  source?: SourceLocation;
+  line?: number;
+  column?: number;
+}
+
+export interface ObjectEntityRef {
+  id: string;
+  kind: ObjectEntityKind;
+}
+
+export interface ObjectEntity {
+  id: string;
+  kind: ObjectEntityKind;
+  label: string;
+  parentId?: string;
+  pageId?: string;
+  blockId?: string;
+  frameKey?: string;
+  chainId?: string;
+  source?: EditableSourceRef;
+  metadata?: Record<string, string | number | boolean | null>;
 }

package/src/openpress/document-model/index.ts

@@ -0,0 +1,6 @@
+export * from "./anchorMapModel";
+export * from "./documentIndexes";
+export * from "./documentTypes";
+export * from "./objectEntityModel";
+export * from "./projectIdentityModel";
+export * from "./reactDocumentMetadataModel";

package/src/openpress/document-model/objectEntityModel.ts

@@ -0,0 +1,51 @@
+import type { ObjectEntity, ObjectEntityKind, ReaderDocument, SourceBlock } from "./documentTypes";
+
+export function createObjectEntityId(kind: ObjectEntityKind, ...parts: Array<string | number>) {
+  return [kind, ...parts.map((part) => encodeURIComponent(String(part)))].join(":");
+}
+
+export function createBlockObjectEntityId(blockId: string) {
+  return createObjectEntityId("mdx-block", blockId);
+}
+
+export function createFrameObjectEntityId(frameKey: string) {
+  return createObjectEntityId("frame", frameKey);
+}
+
+export function createPageObjectEntityId(frameKey: string) {
+  return createObjectEntityId("page", frameKey);
+}
+
+export function createMdxAreaObjectEntityId(frameKey: string, chainId: string, indexInFrame: number) {
+  return createObjectEntityId("mdx-area", frameKey, chainId, indexInFrame);
+}
+
+export function getObjectEntityMap(document: Pick<ReaderDocument, "source"> | null | undefined): Record<string, ObjectEntity> {
+  return document?.source?.objectEntities ?? {};
+}
+
+export function getObjectEntity(document: Pick<ReaderDocument, "source"> | null | undefined, objectId: string): ObjectEntity | null {
+  return getObjectEntityMap(document)[objectId] ?? null;
+}
+
+export function sourceBlockToObjectEntity(block: SourceBlock): ObjectEntity {
+  return {
+    id: createBlockObjectEntityId(block.id),
+    kind: "mdx-block",
+    label: block.name ? `${block.name} ${block.id}` : block.id,
+    blockId: block.id,
+    frameKey: block.frameKey,
+    chainId: block.chainId,
+    pageId: block.frameKey ? createPageObjectEntityId(block.frameKey) : undefined,
+    source: {
+      path: block.path,
+      source: block.source,
+      line: block.source?.line,
+      column: block.source?.column,
+    },
+    metadata: {
+      blockKind: block.kind ?? null,
+      sectionSlug: block.sectionSlug ?? block.chapterSlug ?? null,
+    },
+  };
+}

package/src/openpress/{projectIdentity.ts → document-model/projectIdentityModel.ts}

@@ -1,4 +1,4 @@
-import type { DocumentMeta } from "./types";
+import type { DocumentMeta } from "./documentTypes";
 
 export interface ProjectIdentity {
   name: string;

package/src/openpress/{reactDocumentMetadata.ts → document-model/reactDocumentMetadataModel.ts}

@@ -1,7 +1,7 @@
 import type {
   ReaderDocument,
   SourceBlock,
-} from "./types";
+} from "./documentTypes";
 
 export const PRESS_TREE_MDX_SOURCE_TYPE = "openpress-press-tree-mdx";
 

package/src/openpress/manuscript/index.tsx

@@ -9,9 +9,10 @@
 // document type that wants section flow imports from here; documents that
 // do not (slides, folios, calendars) skip this module entirely.
 
-import { Fragment, useContext, type ReactNode } from "react";
-import { Frame, FrameContext, PressContext, useSource } from "../core";
+import { Fragment, useContext, type ComponentType, type ReactNode } from "react";
+import { Frame, FrameContext, MdxArea, PressContext, useSource } from "../core";
 import type { MdxAreaOverflow, ResolvedSource } from "../core";
+import { createMdxAreaObjectEntityId } from "../document-model/objectEntityModel";
 
 // ---------------------------------------------------------------------------
 // <Sections>
@@ -38,11 +39,11 @@ export interface SectionsOpenerProps {
 
 export interface SectionsProps {
   source: string;
-  page: React.ComponentType<SectionsPageProps>;
-  opener?: React.ComponentType<SectionsOpenerProps>;
+  page?: ComponentType<SectionsPageProps>;
+  opener?: ComponentType<SectionsOpenerProps>;
 }
 
-export function Sections({ source: sourceId, page: Page, opener: Opener }: SectionsProps) {
+export function Sections({ source: sourceId, page: Page = DefaultSectionPage, opener: Opener }: SectionsProps) {
   const source = useSource(sourceId);
   const press = useContext(PressContext);
   const hints = press?.hints ?? null;
@@ -92,6 +93,41 @@ export function Sections({ source: sourceId, page: Page, opener: Opener }: Secti
 export const Chapters = Sections;
 export type ChaptersProps = SectionsProps;
 
+export function DefaultSectionPage({
+  frameKey,
+  chainId,
+  pageIndex,
+  totalPages,
+  sectionSlug,
+  sectionTitle,
+  sectionTone,
+}: SectionsPageProps) {
+  return (
+    <Frame
+      frameKey={frameKey}
+      role="manuscript.content"
+      className="reader-page--content"
+      data-page-index={pageIndex}
+      data-total-pages={totalPages}
+      data-section-id={sectionSlug}
+      data-chapter-tone={sectionTone}
+    >
+      <div className="page-frame">
+        <header className="page-header" aria-hidden="true" />
+        <main className="page-body">
+          <MdxArea chainId={chainId} />
+        </main>
+        <footer className="page-footer" aria-hidden="true">
+          <span className="footer-left">{sectionTitle}</span>
+          <span className="footer-right">
+            {totalPages > 1 ? `${pageIndex + 1}/${totalPages}` : pageIndex + 1}
+          </span>
+        </footer>
+      </div>
+    </Frame>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // <Toc>
 // ---------------------------------------------------------------------------
@@ -178,15 +214,21 @@ function DefaultTocPage({ frameKey, chainId, pageIndex, totalPages, heading, cla
 
 export function TocArea({ chainId, maxLevel, overflow = "extend", className }: TocAreaProps) {
   const frame = useContext(FrameContext);
-  const blocks = frame?.consumeArea(chainId) ?? null;
+  const consumed = frame?.consumeArea(chainId) ?? null;
+  const blocks = consumed?.blocks ?? null;
+  const objectId = frame && consumed
+    ? createMdxAreaObjectEntityId(frame.frameKey, chainId, consumed.indexInFrame)
+    : undefined;
   return (
     <div
       className="openpress-mdx-area openpress-toc-area"
       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-toc-max-level={maxLevel}
       data-openpress-mdx-area-overflow={overflow}
-      data-openpress-mdx-area-empty={blocks == null ? "true" : undefined}
+      data-openpress-mdx-area-empty={blocks == null ? "true" : "false"}
     >
       <ol className={["toc-list", className].filter(Boolean).join(" ") || undefined}>
         {blocks}