@open-press/cli 0.7.1 → 1.0.0

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

@@ -1,4 +1,5 @@
 import type { HTMLAttributes, ReactNode } from "react";
+import type { EditableSourceRef, ObjectEntityKind } from "../document-model/documentTypes";
 
 // ---------------------------------------------------------------------------
 // Frame / MdxArea / Press primitives
@@ -25,8 +26,72 @@ export type MdxAreaProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
   className?: string;
 };
 
+// PageGeometry — a custom fixed-size geometry passed to <Press page>.
+// Same shape as the engine's normalized geometry (CSS lengths,
+// matching units between width / height).
+export interface PageGeometry {
+  id?: string;
+  label?: string;
+  preset?: string;
+  width: string;
+  height: string;
+}
+
+// Source descriptor passed inside <Press sources>. The actual type is
+// the return value of mdxSource() from @open-press/core/mdx; we accept
+// "unknown" at the core boundary to avoid a circular type dependency.
+// The engine validates the shape at render time.
+export type PressSource = unknown;
+
 export interface PressProps {
+  // Document tree — Frames, manuscript helpers, etc.
+  children: ReactNode;
+  // -------------------------------------------------------------------------
+  // 1.0 metadata props — optional during v0.x deprecation, required in v1.0.
+  // -------------------------------------------------------------------------
+  // Document title. Required in 1.0. Used for PDF metadata, HTML <title>,
+  // OG tags, and the Workspace gallery / tab-bar label.
+  title?: string;
+  // Page geometry preset name or a custom geometry object. Optional;
+  // workspace default applies if not set.
+  page?: "a4" | "social-square" | "slide-16-9" | PageGeometry;
+  // Array of source registrations from mdxSource(). Replaces the v0.x
+  // `export const sources` named export.
+  sources?: ReadonlyArray<PressSource>;
+  // URL / output slug for this Press inside a Workspace. Defaults to
+  // "/" when only one Press exists in the Workspace; required when the
+  // Workspace has multiple Press children.
+  slug?: string;
+  // Optional per-Press theme directory. Defaults to "./theme" relative
+  // to the document file; inherits from <Workspace theme> if not set.
+  theme?: string;
+  // Optional per-Press components directory. Default "./components".
+  componentsDir?: string;
+  // Optional caption numbering overrides. Engine defaults to
+  // { figure: "Figure", table: "Table", separator: " " }.
+  captionNumbering?: {
+    figure?: string;
+    table?: string;
+    separator?: string;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Workspace — root component holding one or more Press children
+// ---------------------------------------------------------------------------
+
+export interface WorkspaceProps {
+  // One or more <Press> children. 1 child = single-doc workspace; N
+  // children = multi-doc workspace (proposal + pitch + social, etc).
   children: ReactNode;
+  // Project label surfaced in the gallery header, tab bar, and PDF
+  // metadata. Optional.
+  name?: string;
+  // Workspace-level shared theme directory. Press children that don't
+  // set their own `theme` prop inherit from this. Default "./theme".
+  theme?: string;
+  // Workspace-level shared media directory. Default "./media".
+  media?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -38,6 +103,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"> & {
@@ -45,6 +118,27 @@ export type BaseCalloutProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
   children: ReactNode;
 };
 
+export type ObjectEntityElement = "span" | "div" | "section" | "article" | "figure" | "p";
+
+export type ObjectEntityProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+  as?: ObjectEntityElement;
+  objectId: string;
+  kind: ObjectEntityKind;
+  label: string;
+  parentId?: string;
+  pageId?: string;
+  blockId?: string;
+  frameKey?: string;
+  chainId?: string;
+  source?: EditableSourceRef;
+  metadata?: Record<string, string | number | boolean | null>;
+  children?: ReactNode;
+};
+
+export type TextProps = Omit<ObjectEntityProps, "kind"> & {
+  as?: "span" | "div" | "p";
+};
+
 // ---------------------------------------------------------------------------
 // Source descriptors and resolved sources
 // ---------------------------------------------------------------------------
@@ -140,44 +234,3 @@ export interface ResolvedSource {
 // 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

@@ -21,7 +21,7 @@ export function useSource<T extends ResolvedSource = ResolvedSource>(id: string)
     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.`,
+        `Register it as a <Press sources={[mdxSource({ id: "${id}", ... })]}> entry in press/index.tsx.`,
     );
   }
   return source as T;

package/template/core/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/template/core/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/template/core/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 {
@@ -61,8 +65,12 @@ export interface DocumentMeta {
 }
 
 export interface Theme {
+  pagePreset?: string;
+  pageLabel?: string;
   pageWidth?: string;
   pageHeight?: string;
+  pageAspectRatio?: string;
+  pageHeightRatio?: string;
   pagePadding?: string;
   fontFamily?: string;
   accentColor?: string;
@@ -93,4 +101,47 @@ 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"
+  | "text"
+  | "component"
+  | "media";
+
+export interface EditableSourceRef {
+  path: string;
+  file?: string;
+  kind?: string;
+  objectId?: string;
+  scope?: string;
+  component?: 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/template/core/src/openpress/document-model/index.ts

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

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

@@ -0,0 +1,55 @@
+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 createScopedObjectEntityId(kind: ObjectEntityKind, parentId: string | undefined, objectId: string) {
+  return parentId ? createObjectEntityId(kind, parentId, objectId) : createObjectEntityId(kind, objectId);
+}
+
+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/template/core/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/template/core/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/template/core/src/openpress/document-model/workspaceManifestModel.ts

@@ -0,0 +1,57 @@
+// Shape of /openpress/workspace.json — the reader fetches this on
+// boot to decide between gallery routing (multi-Press) and direct
+// load (single Press). One entry per <Press> child of <Workspace>.
+//
+// Single-Press workspaces emit one entry with slug = "" and the
+// legacy /openpress/document.json path. Multi-Press emits one entry
+// per slug; each `documentUrl` resolves to /openpress/<slug>/document.json.
+
+export interface WorkspaceManifest {
+  version: 1;
+  // <Workspace name="..."> prop. Null when the user did not set one.
+  // Surfaced as the gallery header in the reader.
+  name: string | null;
+  presses: WorkspaceManifestPress[];
+}
+
+export interface WorkspaceManifestPress {
+  // Slug for this Press. Empty string for single-Press workspaces
+  // (legacy root); slug-shaped string for multi-Press.
+  slug: string;
+  // <Press title="..."> prop. Required in v1.0 contract.
+  title: string;
+  // Page geometry summary. Same shape as the reader's
+  // ReaderDocument.theme — readers can show a thumb in the gallery
+  // without loading the full document.json.
+  page: {
+    pagePreset?: string;
+    pageLabel?: string;
+    pageWidth?: string;
+    pageHeight?: string;
+    pageAspectRatio?: string;
+    pageHeightRatio?: string;
+  } | null;
+  // Number of pages produced for this Press.
+  pageCount: number;
+  // Absolute path the reader fetches for this Press's full document.json.
+  documentUrl: string;
+}
+
+// True when the reader should render the gallery first instead of
+// going straight into a single Press's document.
+export function manifestHasMultiplePresses(manifest: WorkspaceManifest): boolean {
+  return manifest.presses.length > 1;
+}
+
+// Find a Press entry by slug. Returns null when the slug is unknown.
+export function findManifestPress(
+  manifest: WorkspaceManifest,
+  slug: string,
+): WorkspaceManifestPress | null {
+  const normalized = slug.replace(/^\/+|\/+$/g, "");
+  for (const press of manifest.presses) {
+    const normalizedSlug = press.slug.replace(/^\/+|\/+$/g, "");
+    if (normalizedSlug === normalized) return press;
+  }
+  return null;
+}

package/template/core/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}

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

@@ -27,14 +27,17 @@ export type {
   SourceNode,
 } from "../core/types";
 
+// All presets accept an optional `id` for the 1.0 contract where sources
+// are an array passed via <Press sources>. In v0.x the id came from the
+// record key in `export const sources = { story: mdxSource(...) }`.
 type MdxSourceOptions =
-  | { preset: "section-folders"; root?: string }
-  | { preset: "section-files"; root?: string }
-  | { preset: "file-list"; files: string[] };
+  | { id?: string; preset: "section-folders"; root?: string }
+  | { id?: string; preset: "section-files"; root?: string }
+  | { id?: string; preset: "file-list"; files: string[] };
 
 const VALID_PRESETS = new Set(["section-folders", "section-files", "file-list"]);
 
-export function mdxSource(options: MdxSourceOptions): MdxSourceDescriptor {
+export function mdxSource(options: MdxSourceOptions): MdxSourceDescriptor & { id?: string } {
   if (!options || typeof options !== "object") {
     throw new Error("mdxSource() requires an options object.");
   }
@@ -46,11 +49,15 @@ export function mdxSource(options: MdxSourceOptions): MdxSourceDescriptor {
     );
   }
 
+  const id = typeof options.id === "string" && options.id.trim() ? options.id.trim() : undefined;
+
   if (options.preset === "section-folders") {
-    return normalizeRooted("section-folders", options.root, "chapters") as MdxSourceDescriptorSectionFolders;
+    const desc = normalizeRooted("section-folders", options.root, "chapters") as MdxSourceDescriptorSectionFolders;
+    return id ? { ...desc, id } : desc;
   }
   if (options.preset === "section-files") {
-    return normalizeRooted("section-files", options.root, "content") as MdxSourceDescriptorSectionFiles;
+    const desc = normalizeRooted("section-files", options.root, "content") as MdxSourceDescriptorSectionFiles;
+    return id ? { ...desc, id } : desc;
   }
 
   // file-list
@@ -69,7 +76,8 @@ export function mdxSource(options: MdxSourceOptions): MdxSourceDescriptor {
   if (files.length === 0) {
     throw new Error('mdxSource({ preset: "file-list" }) requires at least one file.');
   }
-  return { type: "mdx", preset: "file-list", files };
+  const desc: MdxSourceDescriptor = { type: "mdx", preset: "file-list", files };
+  return id ? { ...desc, id } : desc;
 }
 
 function normalizeRooted(