@open-press/core 0.8.0 → 1.1.0

package/src/openpress/core/index.tsx

@@ -6,11 +6,12 @@
 // the engine is not allowed to know about higher-level conventions.
 
 export { Press, PressContext, PRESS_MARKER } from "./Press";
+export { Workspace, WorkspaceContext, WORKSPACE_MARKER } from "./Workspace";
 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 { ObjectEntity, Text, BaseFigure, BaseCallout, MediaFigure, ImageFigure } from "./primitives";
 
 export type {
   FrameProps,
@@ -18,11 +19,16 @@ export type {
   MdxAreaProps,
   MdxAreaOverflow,
   PressProps,
+  PageGeometry,
+  PressSource,
+  WorkspaceProps,
   BaseFigureProps,
   MediaFigureProps,
   BaseCalloutKind,
   BaseCalloutProps,
-  Manifest,
+  ObjectEntityElement,
+  ObjectEntityProps,
+  TextProps,
   // Source-side types are re-exported here for convenience so authors can
   // import `ResolvedSource` from the same place they import primitives.
   ResolvedSource,
@@ -36,5 +42,6 @@ export type {
   FrameAllocation,
 } from "./types";
 
-export type { PressContextValue, AllocationHints } from "./Press";
+export type { PressContextValue, AllocationHints, PressMetadata } from "./Press";
+export type { WorkspaceContextValue } from "./Workspace";
 export type { FrameContextValue } from "./FrameContext";

package/src/openpress/core/primitives.tsx

@@ -1,5 +1,52 @@
 import { cn } from "./cn";
-import type { BaseCalloutProps, BaseFigureProps, MediaFigureProps } from "./types";
+import { useContext } from "react";
+import { FrameContext } from "./FrameContext";
+import type { BaseCalloutProps, BaseFigureProps, MediaFigureProps, ObjectEntityProps, TextProps } from "./types";
+import { createScopedObjectEntityId } from "../document-model/objectEntityModel";
+
+export function ObjectEntity({
+  as: Element = "span",
+  objectId,
+  kind,
+  label,
+  parentId,
+  pageId,
+  blockId,
+  frameKey,
+  chainId,
+  source,
+  metadata,
+  children,
+  ...entityProps
+}: ObjectEntityProps) {
+  const frame = useContext(FrameContext);
+  const resolvedParentId = parentId ?? frame?.objectId;
+  const resolvedPageId = pageId ?? frame?.pageId;
+  const resolvedFrameKey = frameKey ?? frame?.frameKey;
+  const resolvedObjectId = createScopedObjectEntityId(kind, resolvedParentId, objectId);
+
+  return (
+    <Element
+      {...entityProps}
+      data-openpress-object-id={resolvedObjectId}
+      data-openpress-object-kind={kind}
+      data-openpress-object-label={label}
+      data-openpress-object-parent-id={resolvedParentId}
+      data-openpress-object-page-id={resolvedPageId}
+      data-openpress-block-id={blockId}
+      data-openpress-object-frame-key={resolvedFrameKey}
+      data-openpress-object-chain-id={chainId}
+      data-openpress-object-source={source ? JSON.stringify(source) : undefined}
+      data-openpress-object-metadata={metadata ? JSON.stringify(metadata) : undefined}
+    >
+      {children}
+    </Element>
+  );
+}
+
+export function Text(props: TextProps) {
+  return <ObjectEntity {...props} kind="text" />;
+}
 
 export function BaseFigure({ caption, className, children, ...figureProps }: BaseFigureProps) {
   return (

package/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;
 }
 
 // ---------------------------------------------------------------------------
@@ -53,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
 // ---------------------------------------------------------------------------
@@ -148,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/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/src/openpress/document-model/documentTypes.ts

@@ -65,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;
@@ -108,12 +112,17 @@ export type ObjectEntityKind =
   | "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;

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

@@ -4,3 +4,4 @@ export * from "./documentTypes";
 export * from "./objectEntityModel";
 export * from "./projectIdentityModel";
 export * from "./reactDocumentMetadataModel";
+export * from "./workspaceManifestModel";

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

@@ -4,6 +4,10 @@ export function createObjectEntityId(kind: ObjectEntityKind, ...parts: Array<str
   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);
 }

package/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/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(

package/src/openpress/reader/PageThumbnailsPanel.tsx

@@ -0,0 +1,168 @@
+import { useEffect, useRef, useState, type CSSProperties } from "react";
+import type { HtmlPageBlock, Theme } from "../document-model";
+import { Panel } from "../shared";
+
+// Used by canvas-style Press (slides, social posts) that don't have an
+// MDX-derived TOC. Renders each page as a clickable miniature so the user
+// can navigate without bookmarks. The miniature embeds the same HTML
+// that the main reader renders, scaled to fit the panel width.
+
+const FALLBACK_PAGE_WIDTH_PX = 794; // A4 portrait at 96dpi — matches reader default.
+
+export function PageThumbnails({
+  pages,
+  currentPageIndex,
+  onSelectPage,
+  theme,
+}: {
+  pages: HtmlPageBlock[];
+  currentPageIndex: number;
+  onSelectPage: (pageIndex: number, options?: { behavior?: ScrollBehavior }) => void;
+  theme?: Theme;
+}) {
+  const pageWidthPx = parsePxLength(theme?.pageWidth) ?? FALLBACK_PAGE_WIDTH_PX;
+  const pageHeightPx = parsePxLength(theme?.pageHeight) ?? pageWidthPx;
+  // Compute aspect from the parsed dimensions so it always matches the
+  // page render. theme.pageAspectRatio may be missing on per-Press
+  // documents in multi-Press workspaces, which is why we don't read it
+  // here.
+  const aspectRatio = `${pageWidthPx} / ${pageHeightPx}`;
+
+  if (pages.length === 0) {
+    return <Panel.Empty className="openpress-asset-empty" role="status">尚無頁面</Panel.Empty>;
+  }
+
+  return (
+    <ul className="openpress-thumb-list" aria-label="頁面縮圖">
+      {pages.map((page, index) => (
+        <li key={page.id}>
+          <ThumbnailCard
+            page={page}
+            index={index}
+            active={index === currentPageIndex}
+            onClick={() => onSelectPage(index, { behavior: "smooth" })}
+            pageWidthPx={pageWidthPx}
+            pageHeightPx={pageHeightPx}
+            aspectRatio={aspectRatio}
+          />
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function ThumbnailCard({
+  page,
+  index,
+  active,
+  onClick,
+  pageWidthPx,
+  pageHeightPx,
+  aspectRatio,
+}: {
+  page: HtmlPageBlock;
+  index: number;
+  active: boolean;
+  onClick: () => void;
+  pageWidthPx: number;
+  pageHeightPx: number;
+  aspectRatio: string;
+}) {
+  const surfaceRef = useRef<HTMLDivElement>(null);
+  const [scale, setScale] = useState<number | null>(null);
+
+  useEffect(() => {
+    const el = surfaceRef.current;
+    if (!el) return;
+    const update = () => {
+      const w = el.clientWidth;
+      const h = el.clientHeight;
+      if (w > 0 && h > 0) setScale(Math.min(w / pageWidthPx, h / pageHeightPx));
+    };
+    update();
+    if (typeof ResizeObserver === "undefined") return;
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [pageWidthPx, pageHeightPx]);
+
+  const className = `openpress-thumb-card${active ? " is-active" : ""}`;
+  // Wrap the page HTML using the same class structure as the main
+  // reader (`.openpress-html-page > .openpress-html-page__html`) so
+  // section-scoped CSS that targets those classes still applies in
+  // the miniature.
+  const pageClass = page.className
+    ? `openpress-html-page ${page.className}`
+    : "openpress-html-page";
+  const scaledWidth = scale ? pageWidthPx * scale : 0;
+  const scaledHeight = scale ? pageHeightPx * scale : 0;
+  const frameStyle: CSSProperties = {
+    width: `${scaledWidth}px`,
+    height: `${scaledHeight}px`,
+    position: "relative",
+    visibility: scale ? "visible" : "hidden",
+  };
+  const pageStyle: CSSProperties = {
+    "--openpress-page-width": `${pageWidthPx}px`,
+    "--openpress-page-height": `${pageHeightPx}px`,
+    width: `${pageWidthPx}px`,
+    height: `${pageHeightPx}px`,
+    transform: scale ? `scale(${scale})` : undefined,
+    transformOrigin: "top left",
+    position: "absolute",
+    top: 0,
+    left: 0,
+  } as CSSProperties;
+  const pageTitle = page.title || `Page ${index + 1}`;
+
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      className={className}
+      data-openpress-thumb-index={index}
+      aria-label={`前往第 ${index + 1} 頁：${pageTitle}`}
+      aria-current={active ? "page" : undefined}
+      onClick={onClick}
+      onKeyDown={(event) => {
+        if (event.key === "Enter" || event.key === " ") {
+          event.preventDefault();
+          onClick();
+        }
+      }}
+    >
+      <div className="openpress-thumb-card__surface" ref={surfaceRef} style={{ aspectRatio }}>
+        <div className="openpress-thumb-card__frame" style={frameStyle}>
+          <div className={pageClass} style={pageStyle} data-openpress-thumb-page="true">
+            <div
+              className="openpress-html-page__html"
+              // Page HTML comes from the trusted build pipeline (same source
+              // as the main reader).
+              dangerouslySetInnerHTML={{ __html: page.html }}
+            />
+          </div>
+        </div>
+      </div>
+      <div className="openpress-thumb-card__meta">
+        <span className="openpress-thumb-card__index">{String(index + 1).padStart(2, "0")}</span>
+        <span className="openpress-thumb-card__title">{pageTitle}</span>
+      </div>
+    </div>
+  );
+}
+
+function parsePxLength(value: string | undefined): number | null {
+  if (!value) return null;
+  const match = value.trim().match(/^([\d.]+)\s*(px|mm|cm|in)$/i);
+  if (!match) return null;
+  const n = Number(match[1]);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  const unit = match[2].toLowerCase();
+  switch (unit) {
+    case "px": return n;
+    case "mm": return n * (96 / 25.4);
+    case "cm": return n * (96 / 2.54);
+    case "in": return n * 96;
+    default: return null;
+  }
+}

package/src/openpress/reader/index.ts

@@ -1,3 +1,4 @@
+export * from "./PageThumbnailsPanel";
 export * from "./PublicReaderPage";
 export * from "./ReaderNavigationPanel";
 export * from "./pageViewportScaleModel";