@open-press/core 1.2.1 → 1.3.2

package/src/openpress/core/Press.tsx

@@ -14,17 +14,16 @@ export interface AllocationHints {
   totalPagesPerChain: Record<string, number>;
 }
 
-// Metadata read from <Press> props by the engine pipeline. The 1.0 contract
-// declares these on the component; v0.x reads them from openpress.config.mjs
-// instead and leaves these as undefined. The engine merges both sources
-// (props override config) until v1.0 removes config support.
+// Metadata read from <Press> props by the engine pipeline. Each
+// press/<slug>/press.tsx entry declares its document metadata here.
 export interface PressMetadata {
   title?: string;
   type?: PressProps["type"];
   page?: PressProps["page"];
   slug?: string;
   theme?: string;
-  componentsDir?: string;
+  componentsDir?: PressProps["componentsDir"];
+  mediaDir?: PressProps["mediaDir"];
 }
 
 export interface PressContextValue {
@@ -36,9 +35,7 @@ export interface PressContextValue {
   // the first measurement pass.
   hints: AllocationHints | null;
   toc: Record<string, TocEntry[]> | null;
-  // Metadata declared on <Press> props in v1.0. Engine providers may
-  // omit this on v0.x; consumers should treat undefined as "no metadata
-  // declared on Press — fall back to openpress.config.mjs values".
+  // Metadata declared on <Press> props.
   metadata?: PressMetadata;
 }
 
@@ -48,8 +45,6 @@ export function Press(props: PressProps) {
   // Press is intentionally inert at render time — the engine reads its
   // props and children through React.Children inspection during the
   // export pipeline, then injects context above any nested helpers.
-  // For the v0.x shape (children-only usage), this still passes children
-  // through unchanged.
   return <Fragment>{props.children}</Fragment>;
 }
 

package/src/openpress/core/Slide.tsx

@@ -0,0 +1,11 @@
+import { Frame } from "./Frame";
+import type { SlideProps } from "./types";
+
+export function Slide({
+  id,
+  role = "canvas.slide",
+  chrome = false,
+  ...rest
+}: SlideProps) {
+  return <Frame {...rest} frameKey={id} role={role} chrome={chrome} />;
+}

package/src/openpress/core/index.tsx

@@ -8,13 +8,16 @@
 export { Press, PressContext, PRESS_MARKER } from "./Press";
 export { Workspace, WorkspaceContext, WORKSPACE_MARKER } from "./Workspace";
 export { Frame, FRAME_MARKER } from "./Frame";
+export { Slide } from "./Slide";
 export { FrameContext } from "./FrameContext";
+export { PageFolio } from "./PageFolio";
 export { MdxArea } from "./MdxArea";
 export { useSource } from "./useSource";
 export { ObjectEntity, Text, BaseFigure, BaseCallout, MediaFigure, ImageFigure } from "./primitives";
 
 export type {
   FrameProps,
+  SlideProps,
   FrameRole,
   MdxAreaProps,
   MdxAreaOverflow,
@@ -45,3 +48,4 @@ export type {
 export type { PressContextValue, AllocationHints, PressMetadata } from "./Press";
 export type { WorkspaceContextValue } from "./Workspace";
 export type { FrameContextValue } from "./FrameContext";
+export type { PageFolioNumberFormat, PageFolioProps, PageFolioVariant } from "./PageFolio";

package/src/openpress/core/types.ts

@@ -18,6 +18,12 @@ export type FrameProps = Omit<HTMLAttributes<HTMLElement>, "role" | "children">
   children?: ReactNode;
 };
 
+export type SlideProps = Omit<FrameProps, "frameKey" | "role" | "chrome" | "title"> & {
+  id: string;
+  role?: FrameRole;
+  chrome?: boolean;
+};
+
 export type MdxAreaOverflow = "extend" | "truncate" | "error";
 
 export type MdxAreaProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
@@ -47,9 +53,9 @@ export interface PressProps {
   // Document tree — Frames, manuscript helpers, etc.
   children: ReactNode;
   // -------------------------------------------------------------------------
-  // 1.0 metadata props — optional during v0.x deprecation, required in v1.0.
+  // Press metadata props.
   // -------------------------------------------------------------------------
-  // Document title. Required in 1.0. Used for PDF metadata, HTML <title>,
+  // Document title. Used for PDF metadata, HTML <title>,
   // OG tags, and the Workspace gallery / tab-bar label.
   title?: string;
   // Creation mode. Pages are source-driven with MDX allocation; slides are
@@ -61,15 +67,17 @@ export interface PressProps {
   // 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.
+  // URL / output slug for this Press. Must match the Press folder name.
   slug?: string;
-  // Optional per-Press theme directory. Defaults to "./theme" relative
-  // to the document file; inherits from <Workspace theme> if not set.
+  // Optional per-Press theme directory. Defaults include the folder-local
+  // "./theme"; shared CSS lives in press/shared/theme.
   theme?: string;
-  // Optional per-Press components directory. Default "./components".
-  componentsDir?: string;
+  // Optional per-Press components directories. Defaults include the
+  // folder-local "./components" and workspace shared components.
+  componentsDir?: string | string[];
+  // Optional per-Press media directories. Defaults include the folder-local
+  // "./media" and workspace shared media.
+  mediaDir?: string | string[];
   // Optional caption numbering overrides. Engine defaults to
   // { figure: "Figure", table: "Table", separator: " " }.
   captionNumbering?: {
@@ -80,7 +88,8 @@ export interface PressProps {
 }
 
 // ---------------------------------------------------------------------------
-// Workspace — root component holding one or more Press children
+// Workspace — engine-owned grouping component holding one or more Press
+// children from discovered press/*/press.tsx entries.
 // ---------------------------------------------------------------------------
 
 export interface WorkspaceProps {
@@ -90,10 +99,9 @@ export interface WorkspaceProps {
   // 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".
+  // Reserved for future workspace-level shared theme overrides.
   theme?: string;
-  // Workspace-level shared media directory. Default "./media".
+  // Reserved for future workspace-level shared media overrides.
   media?: 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 as a <Press sources={[mdxSource({ id: "${id}", ... })]}> entry in press/index.tsx.`,
+        `Register it as a <Press sources={[mdxSource({ id: "${id}", ... })]}> entry in press/<slug>/press.tsx.`,
     );
   }
   return source as T;

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

@@ -1,10 +1,6 @@
 // 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.
+// load (single Press). One entry per discovered Press folder.
 import type { PressType } from "./documentTypes";
 
 export interface WorkspaceManifest {
@@ -16,13 +12,12 @@ export interface WorkspaceManifest {
 }
 
 export interface WorkspaceManifestPress {
-  // Slug for this Press. Empty string for single-Press workspaces
-  // (legacy root); slug-shaped string for multi-Press.
+  // Slug for this Press. Matches the folder-convention Press slug.
   slug: string;
   // <Press title="..."> prop. Required in v1.0 contract.
   title: string;
-  // Creation mode declared by <Press type>. Defaults to "pages" for older
-  // documents. The reader uses this for mode-specific navigation affordances.
+  // Creation mode declared by <Press type>. The reader uses this for
+  // mode-specific navigation affordances.
   type: PressType;
   // Page geometry summary. Same shape as the reader's
   // ReaderDocument.theme — readers can show a thumb in the gallery

package/src/openpress/reader/SlidePresentationPage.tsx

@@ -29,9 +29,13 @@ export function SlidePresentationPage({
     if (typeof window === "undefined") return 0;
     return pageIndexFromHash(window.location.hash, normalizedPageCount) ?? 0;
   });
-  const [uiMode, setUiMode] = useState<PresentationUiMode>(() => (
-    shouldStartImmersive() ? "immersive" : "chrome"
-  ));
+  const [uiMode, setUiMode] = useState<PresentationUiMode>(() => {
+    if (shouldStartImmersive()) return "immersive";
+    // Fullscreen may already be active if requestFullscreen() was called
+    // synchronously in the workbench click handler before in-place navigation.
+    if (typeof globalThis.document !== "undefined" && globalThis.document.fullscreenElement) return "immersive";
+    return "chrome";
+  });
   const pageViewport = usePageViewportScale({
     stageRef,
     pageContainerRef: sourceContainerRef,

package/src/openpress/workbench/shell/WorkbenchToolbarActions.tsx

@@ -98,36 +98,9 @@ export function WorkbenchToolbarActions({
           </button>
         </div>
       ) : null}
-      <div className="openpress-workbench-toolbar__group" aria-label="匯出">
-        <ExportControl
-          pages={pages}
-          currentPageIndex={currentPageIndex}
-          pressTitle={pressTitle}
-          theme={theme}
-          onExportPdf={onExportPdf}
-          pdfDisabled={pdfDisabled}
-          pdfLabel={pdfLabel}
-          pdfStatusMessage={pdfStatusMessage}
-          pdfActionStatus={pdfActionStatus}
-        />
-      </div>
-      <div className="openpress-workbench-toolbar__group openpress-workbench-toolbar__group--page" aria-label="頁面規格">
-        {isSlidePress && onOpenPresentation ? (
-          <button
-            type="button"
-            className="openpress-workbench-toolbar-action"
-            data-openpress-slide-present
-            data-openpress-toolbar-expanded="false"
-            data-openpress-toolbar-active="false"
-            aria-pressed="false"
-            title="進入放映模式"
-            aria-label="進入放映模式"
-            onClick={() => onOpenPresentation(currentPageIndex)}
-          >
-            <Play aria-hidden="true" />
-            <span className="openpress-workbench-toolbar-action__label">放映</span>
-          </button>
-        ) : null}
+
+      {/* Center group: page geometry / zoom + workspace tools */}
+      <div className="openpress-workbench-toolbar__group openpress-workbench-toolbar__group--page" aria-label="頁面規格與工具">
         <button
           type="button"
           className="openpress-workbench-page-geometry"
@@ -146,25 +119,15 @@ export function WorkbenchToolbarActions({
           onScaleModeChange={onScaleModeChange}
           onPageLayoutModeChange={onPageLayoutModeChange}
         />
-      </div>
-      <div className="openpress-workbench-toolbar__group openpress-workbench-toolbar__group--right" aria-label="工作台狀態與發布">
+        {workspaceMode ? (
+          <span className="openpress-workbench-toolbar__sep" aria-hidden="true" />
+        ) : null}
         {workspaceMode ? (
           <SearchControl
             sourceBlocksByPath={sourceBlocksByPath}
             onSelectPage={onSelectPage}
           />
         ) : null}
-        {workspaceMode && editStatusMessage ? (
-          <span
-            className="openpress-dev-edit-status openpress-dev-edit-status--toolbar"
-            data-openpress-edit-status={inlineEditStatus.state}
-            role="status"
-            aria-live="polite"
-          >
-            {inlineEditStatus.state === "saving" ? <span className="openpress-dev-edit-status__spinner" aria-hidden="true" /> : null}
-            <span>{editStatusMessage}</span>
-          </span>
-        ) : null}
         {workspaceMode ? (
           <button
             type="button"
@@ -183,6 +146,17 @@ export function WorkbenchToolbarActions({
             <span className="openpress-dev-inspector-status">{inspectorSelectionLabel}</span>
           </button>
         ) : null}
+        {workspaceMode && editStatusMessage ? (
+          <span
+            className="openpress-dev-edit-status openpress-dev-edit-status--toolbar"
+            data-openpress-edit-status={inlineEditStatus.state}
+            role="status"
+            aria-live="polite"
+          >
+            {inlineEditStatus.state === "saving" ? <span className="openpress-dev-edit-status__spinner" aria-hidden="true" /> : null}
+            <span>{editStatusMessage}</span>
+          </span>
+        ) : null}
         {workspaceMode && inspectorMode ? (
           <span
             className="openpress-dev-inspector-status"
@@ -193,6 +167,21 @@ export function WorkbenchToolbarActions({
             {inspectorCommentStatusMessage}
           </span>
         ) : null}
+      </div>
+
+      {/* Right group: export + deploy + present */}
+      <div className="openpress-workbench-toolbar__group openpress-workbench-toolbar__group--right" aria-label="匯出與發布">
+        <ExportControl
+          pages={pages}
+          currentPageIndex={currentPageIndex}
+          pressTitle={pressTitle}
+          theme={theme}
+          onExportPdf={onExportPdf}
+          pdfDisabled={pdfDisabled}
+          pdfLabel={pdfLabel}
+          pdfStatusMessage={pdfStatusMessage}
+          pdfActionStatus={pdfActionStatus}
+        />
         {localDeployEnabled ? (
           <DeploymentControl
             info={deploymentInfo}
@@ -200,6 +189,20 @@ export function WorkbenchToolbarActions({
             onDeploy={onDeploy}
           />
         ) : null}
+        {isSlidePress && onOpenPresentation ? (
+          <button
+            type="button"
+            className="openpress-workbench-toolbar-action openpress-workbench-toolbar-action--primary"
+            data-openpress-slide-present
+            aria-pressed="false"
+            title="進入放映模式"
+            aria-label="進入放映模式"
+            onClick={() => onOpenPresentation(currentPageIndex)}
+          >
+            <Play aria-hidden="true" />
+            <span className="openpress-workbench-toolbar-action__label">放映</span>
+          </button>
+        ) : null}
       </div>
     </>
   );

package/src/styles/openpress/workbench-toolbar.css

@@ -235,6 +235,15 @@
   height: 1px;
 }
 
+.openpress-workbench-toolbar__sep {
+  display: block;
+  width: 1px;
+  height: 16px;
+  flex: 0 0 auto;
+  background: rgb(255 255 255 / 10%);
+  border-radius: 1px;
+}
+
 .openpress-workbench-toolbar-action {
   position: relative;
   display: inline-flex;
@@ -279,6 +288,30 @@
   opacity: 0.62;
 }
 
+.openpress-workbench-toolbar-action--primary {
+  width: auto;
+  min-width: 30px;
+  max-width: min(34vw, 300px);
+  gap: 7px;
+  padding: 0 12px;
+  background: var(--openpress-accent, #df4b21);
+  border-color: transparent;
+  color: #fff;
+}
+
+.openpress-workbench-toolbar-action--primary .openpress-workbench-toolbar-action__label {
+  display: inline-flex;
+}
+
+.openpress-workbench-toolbar-action--primary:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--openpress-accent, #df4b21) 82%, #fff);
+  color: #fff;
+}
+
+.openpress-workbench-toolbar-action--primary:active:not(:disabled) {
+  transform: translateY(1px);
+}
+
 .openpress-workbench-toolbar-action[data-openpress-toolbar-expanded="true"] {
   width: auto;
   min-width: 30px;

package/src/styles/openpress/workspace-gallery.css

@@ -4,10 +4,8 @@
    load the document directly, so this CSS is dormant until users
    add a second <Press> to their <Workspace>.
 
-   Layout intent: Figma-style file grid — uniform card width, fixed
-   thumbnail aspect ratio (4:3), filename + meta below. Each card
-   loads its first page asynchronously and renders it scaled-down
-   inside the thumbnail slot. */
+   Layout: full-height dark page, header + two-column body
+   (narrow left sidebar for type filter, fluid right grid). */
 
 .openpress-workspace-gallery {
   --workspace-bg: #10110f;
@@ -20,10 +18,10 @@
   --workspace-card-muted: #65635d;
   --workspace-card-line: rgba(20, 20, 17, 0.1);
   --workspace-card-stage: #e8e5dc;
-  display: grid;
-  gap: 2rem;
+  --workspace-sidebar-w: 180px;
+  display: flex;
+  flex-direction: column;
   min-height: 100vh;
-  max-width: none;
   margin: 0;
   padding: 3.6rem clamp(2rem, 4vw, 4.5rem) 6rem;
   font-family: var(--openpress-font-body, system-ui, sans-serif);
@@ -31,11 +29,13 @@
   background:
     linear-gradient(180deg, var(--workspace-bg-soft), var(--workspace-bg) 42rem),
     var(--workspace-bg);
+  gap: 2.25rem;
 }
 
+/* ── Header ──────────────────────────────────────────────── */
+
 .openpress-workspace-gallery__header {
-  display: grid;
-  grid-template-columns: minmax(0, 1fr) auto;
+  display: flex;
   align-items: end;
   justify-content: space-between;
   gap: 2.5rem;
@@ -48,50 +48,114 @@
   gap: 0.75rem;
 }
 
-.openpress-workspace-gallery__eyebrow {
+.openpress-workspace-gallery__brand {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
   margin: 0;
-  color: var(--workspace-muted);
   font-family: var(--openpress-font-mono, ui-monospace, monospace);
   font-size: 0.68rem;
   font-weight: 600;
-  letter-spacing: 0.16em;
+  letter-spacing: 0.12em;
   text-transform: uppercase;
 }
 
+.openpress-workspace-gallery__brand-mark {
+  color: var(--workspace-ink);
+}
+
+.openpress-workspace-gallery__brand-sep {
+  color: var(--workspace-muted);
+  letter-spacing: 0;
+}
+
+.openpress-workspace-gallery__eyebrow {
+  color: var(--workspace-muted);
+}
+
 .openpress-workspace-gallery__header h1 {
   margin: 0;
   font-family: var(--openpress-font-display, var(--openpress-font-body, system-ui));
-  font-size: clamp(2.6rem, 5.4vw, 5.2rem);
-  font-weight: 720;
-  line-height: 0.94;
-  letter-spacing: -0.035em;
+  font-size: clamp(1.4rem, 2.6vw, 2.2rem);
+  font-weight: 600;
+  line-height: 1.1;
+  letter-spacing: -0.02em;
   color: var(--workspace-ink);
 }
 
-.openpress-workspace-gallery__count {
-  margin: 0;
+/* ── Body: sidebar + grid ────────────────────────────────── */
+
+.openpress-workspace-gallery__body {
   display: grid;
-  justify-items: end;
-  gap: 0.25rem;
-  min-width: 4.5rem;
+  grid-template-columns: var(--workspace-sidebar-w) 1fr;
+  align-items: start;
+  gap: 2.5rem;
+}
+
+/* ── Left sidebar ────────────────────────────────────────── */
+
+.openpress-workspace-gallery__sidebar {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  position: sticky;
+  top: 1.5rem;
+}
+
+.openpress-workspace-gallery__filter-btn {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.6rem;
+  width: 100%;
+  padding: 0.52rem 0.75rem;
+  border: 1px solid transparent;
+  border-radius: 7px;
+  background: transparent;
+  color: var(--workspace-muted);
+  font-family: var(--openpress-font-body, system-ui, sans-serif);
+  font-size: 0.82rem;
+  font-weight: 500;
+  text-align: left;
+  cursor: pointer;
+  transition:
+    background 140ms ease,
+    color 140ms ease,
+    border-color 140ms ease;
+}
+
+.openpress-workspace-gallery__filter-btn:hover {
+  background: rgba(244, 241, 232, 0.06);
   color: var(--workspace-ink);
-  font-family: var(--openpress-font-mono, ui-monospace, monospace);
-  line-height: 1;
 }
 
-.openpress-workspace-gallery__count span {
+.openpress-workspace-gallery__filter-btn[data-active="true"] {
+  background: rgba(244, 241, 232, 0.1);
+  border-color: rgba(244, 241, 232, 0.14);
   color: var(--workspace-ink);
-  font-size: 2rem;
-  font-weight: 500;
-  letter-spacing: -0.04em;
 }
 
-.openpress-workspace-gallery__count small {
+.openpress-workspace-gallery__filter-label {
+  flex: 1 1 auto;
+}
+
+.openpress-workspace-gallery__filter-count {
+  flex: 0 0 auto;
+  font-family: var(--openpress-font-mono, ui-monospace, monospace);
+  font-size: 0.72rem;
+  font-weight: 500;
   color: var(--workspace-muted);
-  font-size: 0.62rem;
-  font-weight: 600;
-  letter-spacing: 0.14em;
-  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.openpress-workspace-gallery__filter-btn[data-active="true"] .openpress-workspace-gallery__filter-count {
+  color: var(--workspace-ink);
+}
+
+/* ── Main grid ───────────────────────────────────────────── */
+
+.openpress-workspace-gallery__main {
+  min-width: 0;
 }
 
 .openpress-workspace-gallery__grid {
@@ -100,8 +164,6 @@
   padding: 0;
   display: grid;
   align-items: start;
-  /* Uniform card size — Figma-style. Outer thumb is fixed 4:3, the
-     inner page letterboxes to its own geometry. */
   grid-template-columns: repeat(auto-fill, minmax(20rem, 1fr));
   gap: 1.5rem;
 }
@@ -110,6 +172,15 @@
   display: flex;
 }
 
+.openpress-workspace-gallery__empty {
+  margin: 0;
+  padding: 3rem 0;
+  color: var(--workspace-muted);
+  font-size: 0.88rem;
+}
+
+/* ── Card ────────────────────────────────────────────────── */
+
 .openpress-workspace-gallery__card {
   appearance: none;
   display: grid;
@@ -138,13 +209,12 @@
   outline: none;
 }
 
+/* ── Thumbnail ───────────────────────────────────────────── */
+
 .openpress-workspace-gallery__thumb {
   position: relative;
   display: block;
   width: 100%;
-  /* Uniform 4:3 outer slot across every card. The page itself
-     letterboxes inside via centered scale, so each Press shows at its
-     own true aspect against the gradient background. */
   aspect-ratio: 4 / 3;
   background:
     linear-gradient(
@@ -220,7 +290,9 @@
   50%      { opacity: 0.55; }
 }
 
-.openpress-workspace-gallery__body {
+/* ── Card body ───────────────────────────────────────────── */
+
+.openpress-workspace-gallery__card-body {
   display: grid;
   align-content: space-between;
   gap: 1.2rem;
@@ -262,10 +334,6 @@
   white-space: nowrap;
 }
 
-.openpress-workspace-gallery__geom {
-  color: var(--workspace-card-muted);
-}
-
 .openpress-workspace-gallery__geom {
   display: inline-flex;
   align-items: center;
@@ -279,16 +347,31 @@
   white-space: nowrap;
 }
 
+/* ── Responsive ──────────────────────────────────────────── */
+
+@media (max-width: 860px) {
+  .openpress-workspace-gallery__body {
+    grid-template-columns: 1fr;
+  }
+
+  .openpress-workspace-gallery__sidebar {
+    position: static;
+    flex-direction: row;
+    flex-wrap: wrap;
+    gap: 6px;
+  }
+
+  .openpress-workspace-gallery__filter-btn {
+    width: auto;
+    flex: 0 0 auto;
+  }
+}
+
 @media (max-width: 720px) {
   .openpress-workspace-gallery {
     padding: 2.25rem 1rem 4rem;
   }
 
-  .openpress-workspace-gallery__header {
-    display: grid;
-    align-items: start;
-  }
-
   .openpress-workspace-gallery__grid {
     grid-template-columns: 1fr;
   }