@open-press/core 0.3.0

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@open-press/core",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "open-press core — runtime primitives, CLI, and render pipeline for AI-first fixed-layout documents.",
+  "license": "MIT",
+  "author": "quan0715",
+  "homepage": "https://github.com/quan0715/open-press#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quan0715/open-press.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/quan0715/open-press/issues"
+  },
+  "keywords": [
+    "document",
+    "mdx",
+    "react",
+    "pdf",
+    "a4",
+    "fixed-layout",
+    "ai-first"
+  ],
+  "main": "./src/openpress/core/index.tsx",
+  "types": "./src/openpress/core/index.tsx",
+  "exports": {
+    ".": "./src/openpress/core/index.tsx"
+  },
+  "bin": {
+    "open-press": "engine/cli.mjs"
+  },
+  "files": [
+    "engine",
+    "src/openpress",
+    "src/styles",
+    "index.html",
+    "vite.config.ts",
+    "tsconfig.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mdx-js/mdx": "^3.1.1",
+    "@mdx-js/react": "^3.1.1",
+    "js-yaml": "^4.1.1",
+    "katex": "^0.16.47",
+    "lucide-react": "^1.16.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "rehype-katex": "^7.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.60.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^25.8.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    "jsdom": "^26.1.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.13",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "dev": "node engine/cli.mjs dev . --renderer react",
+    "build": "node engine/cli.mjs render . --renderer react",
+    "preview": "node engine/cli.mjs preview . --renderer react",
+    "typecheck": "node engine/cli.mjs typecheck .",
+    "test": "pnpm run test:node && pnpm run test:react",
+    "test:e2e:reader": "playwright test --config playwright.reader.config.ts",
+    "test:node": "node --test tests/*.test.mjs",
+    "test:react": "vitest run",
+    "openpress:validate": "node engine/cli.mjs validate .",
+    "openpress:export": "node engine/cli.mjs export .",
+    "openpress:pdf": "node engine/cli.mjs pdf .",
+    "openpress:render": "node engine/cli.mjs render . --renderer react",
+    "openpress:preview": "node engine/cli.mjs preview . --renderer react",
+    "openpress:deploy": "node engine/cli.mjs deploy .",
+    "openpress:deploy:dry-run": "node engine/cli.mjs deploy . --confirm --dry-run"
+  }
+}

package/src/openpress/App.tsx

@@ -0,0 +1,127 @@
+import { useEffect, useState } from "react";
+import { Renderer } from "./renderer";
+import { isLocalWorkspaceHost } from "./runtimeMode";
+import type { DeploymentInfo, ReaderDocument } from "./types";
+
+type LoadState =
+  | { status: "loading" }
+  | {
+      status: "ready";
+      document: ReaderDocument;
+      deploymentInfo: DeploymentInfo;
+    }
+  | { status: "error"; message: string };
+
+interface DeployConfig {
+  pdf?: string;
+  deployed_at?: string;
+  public_url?: string;
+  dirty?: boolean;
+  deploy_configured?: boolean;
+  deploy_adapter?: string;
+  deploy_source?: string;
+  deploy_project_name?: string | null;
+  deploy_setup_message?: string;
+}
+
+const offlineDeploymentInfo: DeploymentInfo = { online: false };
+
+function LoadingScreen() {
+  return (
+    <div className="openpress-loading-screen" aria-label="載入中" role="status">
+      <div className="openpress-loading-screen__inner">
+        <div className="openpress-loading-dots" aria-hidden="true">
+          <span /><span /><span />
+        </div>
+        <span className="openpress-loading-screen__label">載入文件</span>
+      </div>
+    </div>
+  );
+}
+
+export function App() {
+  const [state, setState] = useState<LoadState>({ status: "loading" });
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function loadDocument() {
+      try {
+        const [response, deploymentInfo] = await Promise.all([
+          fetch("/openpress/document.json", { cache: "no-store" }),
+          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 });
+        }
+      } catch (error) {
+        if (!cancelled) {
+          setState({
+            status: "error",
+            message: error instanceof Error ? error.message : "Unable to load OpenPress document.",
+          });
+        }
+      }
+    }
+
+    void loadDocument();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  if (state.status === "loading") return <LoadingScreen />;
+
+  if (state.status === "error") {
+    return <div className="openpress-load-state openpress-load-state--error">{state.message}</div>;
+  }
+
+  return (
+    <Renderer
+      document={state.document}
+      deploymentInfo={state.deploymentInfo}
+    />
+  );
+}
+
+async function loadDeploymentInfo(): Promise<DeploymentInfo> {
+  if (typeof window !== "undefined" && isLocalWorkspaceHost(window.location.hostname)) {
+    const localInfo = await loadDeploymentInfoFrom("/__openpress/status");
+    if (localInfo) return localInfo;
+  }
+
+  return (await loadDeploymentInfoFrom("/openpress/deploy.json")) ?? offlineDeploymentInfo;
+}
+
+async function loadDeploymentInfoFrom(path: string): Promise<DeploymentInfo | null> {
+  try {
+    const response = await fetch(path, { cache: "no-store" });
+    if (!response.ok) {
+      return null;
+    }
+    const config = (await response.json()) as DeployConfig;
+    return deploymentConfigToInfo(config);
+  } catch {
+    return null;
+  }
+}
+
+function deploymentConfigToInfo(config: DeployConfig): DeploymentInfo {
+  const configured = config.deploy_configured !== false;
+  return {
+    online: configured && Boolean(config.deployed_at || config.public_url),
+    deployedAt: config.deployed_at,
+    pdf: typeof config.pdf === "string" ? config.pdf : undefined,
+    publicUrl: typeof config.public_url === "string" ? config.public_url : undefined,
+    dirty: config.dirty === true,
+    configured,
+    adapter: typeof config.deploy_adapter === "string" ? config.deploy_adapter : undefined,
+    source: typeof config.deploy_source === "string" ? config.deploy_source : undefined,
+    projectName: typeof config.deploy_project_name === "string" ? config.deploy_project_name : undefined,
+    setupMessage: typeof config.deploy_setup_message === "string" ? config.deploy_setup_message : undefined,
+  };
+}

package/src/openpress/composerMentions.ts

@@ -0,0 +1,188 @@
+import { useEffect, useMemo, useState, type KeyboardEvent, type RefObject } from "react";
+
+export type ComposerMentionItem = {
+  trigger: "@" | "/";
+  value: string;
+  label: string;
+  meta: string;
+  kind: "media" | "component" | "skill" | "chapter" | "section" | "prefix";
+};
+
+export type ActiveComposerMention = {
+  trigger: "@" | "/";
+  query: string;
+  start: number;
+  end: number;
+};
+
+export function useComposerMentions({
+  text,
+  items,
+  textareaRef,
+  onTextChange,
+  enabled = true,
+  maxSuggestions = 7,
+}: {
+  text: string;
+  items: ComposerMentionItem[];
+  textareaRef: RefObject<HTMLTextAreaElement | null>;
+  onTextChange: (value: string) => void;
+  enabled?: boolean;
+  maxSuggestions?: number;
+}) {
+  const [composerCursor, setComposerCursor] = useState(0);
+  const [highlightedMentionIndex, setHighlightedMentionIndex] = useState(0);
+  const [dismissedMentionKey, setDismissedMentionKey] = useState<string | null>(null);
+  const activeMention = enabled ? resolveComposerMention(text, composerCursor) : null;
+  const mentionKey = activeMention ? `${activeMention.trigger}:${activeMention.start}:${activeMention.query}` : null;
+  const mentionSuggestions = useMemo(() => {
+    if (!activeMention) return [];
+    if (mentionKey && dismissedMentionKey === mentionKey) return [];
+    return createMentionSuggestions(activeMention, items, maxSuggestions);
+  }, [activeMention, dismissedMentionKey, items, maxSuggestions, mentionKey]);
+
+  useEffect(() => {
+    setHighlightedMentionIndex(0);
+  }, [mentionKey, mentionSuggestions.length]);
+
+  const syncCursor = () => {
+    const textarea = textareaRef.current;
+    if (textarea) setComposerCursor(textarea.selectionStart ?? text.length);
+  };
+
+  const insertMention = (item: ComposerMentionItem) => {
+    if (!activeMention) return;
+    const suffix = item.kind === "prefix" ? "" : " ";
+    const nextText = `${text.slice(0, activeMention.start)}${item.value}${suffix}${text.slice(activeMention.end)}`;
+    const nextCursor = activeMention.start + item.value.length + suffix.length;
+    setDismissedMentionKey(null);
+    onTextChange(nextText);
+    if (typeof window === "undefined") return;
+    window.requestAnimationFrame(() => {
+      textareaRef.current?.focus();
+      textareaRef.current?.setSelectionRange(nextCursor, nextCursor);
+      setComposerCursor(nextCursor);
+    });
+  };
+
+  const handleMentionKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
+    if (!activeMention || mentionSuggestions.length === 0) return false;
+    if (event.key === "ArrowDown") {
+      event.preventDefault();
+      setHighlightedMentionIndex((index) => (index + 1) % mentionSuggestions.length);
+      return true;
+    }
+    if (event.key === "ArrowUp") {
+      event.preventDefault();
+      setHighlightedMentionIndex((index) => (index - 1 + mentionSuggestions.length) % mentionSuggestions.length);
+      return true;
+    }
+    if (event.key === "Enter" || event.key === "Tab") {
+      event.preventDefault();
+      insertMention(mentionSuggestions[highlightedMentionIndex] ?? mentionSuggestions[0]);
+      return true;
+    }
+    if (event.key === "Escape") {
+      event.preventDefault();
+      setDismissedMentionKey(mentionKey);
+      return true;
+    }
+    return false;
+  };
+
+  return {
+    activeMention,
+    handleMentionKeyDown,
+    highlightedMentionIndex,
+    setHighlightedMentionIndex,
+    mentionSuggestions,
+    setComposerCursor,
+    syncCursor,
+    insertMention,
+  };
+}
+
+export function appendComposerToken(text: string, token: string) {
+  const trimmedToken = token.trim();
+  if (!trimmedToken) return text;
+  if (!text.trim()) return `${trimmedToken} `;
+  return `${text.replace(/\s*$/, " ")}${trimmedToken} `;
+}
+
+export function createMentionSuggestions(
+  activeMention: ActiveComposerMention,
+  items: ComposerMentionItem[],
+  maxSuggestions: number,
+) {
+  if (activeMention.trigger === "@") {
+    const prefixItems = createMentionPrefixItems(items);
+    const normalizedQuery = activeMention.query.trim().toLowerCase();
+    if (!normalizedQuery) return prefixItems.slice(0, maxSuggestions);
+    if (!normalizedQuery.includes("/")) {
+      return uniqueMentionItems([
+        ...prefixItems.filter((item) => mentionMatches(item, normalizedQuery)),
+        ...items.filter((item) => item.trigger === "@" && mentionMatches(item, normalizedQuery)),
+      ]).slice(0, maxSuggestions);
+    }
+  }
+
+  return items
+    .filter((item) => item.trigger === activeMention.trigger && mentionMatches(item, activeMention.query))
+    .slice(0, maxSuggestions);
+}
+
+function createMentionPrefixItems(items: ComposerMentionItem[]): ComposerMentionItem[] {
+  const availableKinds = new Set(items.filter((item) => item.trigger === "@").map((item) => item.kind));
+  return MENTION_PREFIX_DEFINITIONS
+    .filter((item) => availableKinds.has(item.kind))
+    .map((item) => ({
+      trigger: "@" as const,
+      value: `@${item.kind}/`,
+      label: item.kind,
+      meta: item.meta,
+      kind: "prefix" as const,
+    }));
+}
+
+function uniqueMentionItems(items: ComposerMentionItem[]) {
+  const seen = new Set<string>();
+  return items.filter((item) => {
+    const key = `${item.kind}:${item.value}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function resolveComposerMention(text: string, cursor: number): ActiveComposerMention | null {
+  const safeCursor = clampNumber(cursor, 0, text.length);
+  const beforeCursor = text.slice(0, safeCursor);
+  const match = beforeCursor.match(/(^|\s)([@/])([^\s@]*)$/);
+  if (!match) return null;
+  const start = beforeCursor.length - match[0].length + match[1].length;
+  return {
+    trigger: match[2] as "@" | "/",
+    query: match[3] ?? "",
+    start,
+    end: safeCursor,
+  };
+}
+
+function mentionMatches(item: ComposerMentionItem, query: string) {
+  const normalizedQuery = query.trim().toLowerCase();
+  if (!normalizedQuery) return true;
+  return item.value.toLowerCase().includes(normalizedQuery)
+    || item.label.toLowerCase().includes(normalizedQuery)
+    || item.meta.toLowerCase().includes(normalizedQuery);
+}
+
+function clampNumber(value: number, min: number, max: number) {
+  return Math.min(Math.max(value, min), Math.max(min, max));
+}
+
+const MENTION_PREFIX_DEFINITIONS: Array<{ kind: "media" | "chapter" | "section" | "component"; meta: string }> = [
+  { kind: "media", meta: "prefix · images" },
+  { kind: "chapter", meta: "prefix · chapters" },
+  { kind: "section", meta: "prefix · sections" },
+  { kind: "component", meta: "prefix · components" },
+];

package/src/openpress/core/basePages.tsx

@@ -0,0 +1,87 @@
+import type {
+  BaseCalloutProps,
+  BaseFigureProps,
+  BasePageProps,
+  BaseContentPageProps,
+  BaseShellPageProps,
+} from "./types";
+
+function classNames(...values: Array<string | undefined>) {
+  const joined = values.filter(Boolean).join(" ");
+  return joined.length > 0 ? joined : undefined;
+}
+
+export function BasePage({ kind, footer = true, className, children, ...sectionProps }: BasePageProps) {
+  return (
+    <section
+      {...sectionProps}
+      className={classNames("reader-page", `reader-page--${kind}`, className)}
+      data-page-footer={footer ? "true" : "false"}
+      data-page-kind={kind}
+    >
+      {children}
+    </section>
+  );
+}
+
+export function BaseCoverPage(props: BaseShellPageProps) {
+  return <BasePage {...props} footer={false} kind="cover" />;
+}
+
+export function BaseTocPage(props: BaseShellPageProps) {
+  return <BasePage {...props} footer={false} kind="toc" />;
+}
+
+export function BaseContentPage({
+  pageIndex,
+  totalPages,
+  chapterSlug,
+  chapterTone,
+  runningHeader,
+  footerLeft,
+  footerRight,
+  children,
+  ...sectionProps
+}: BaseContentPageProps) {
+  return (
+    <BasePage
+      {...sectionProps}
+      data-chapter-slug={chapterSlug}
+      data-chapter-tone={chapterTone}
+      data-page-index={pageIndex}
+      data-total-pages={totalPages}
+      footer
+      kind="content"
+    >
+      {runningHeader === undefined ? null : <header data-page-running-header>{runningHeader}</header>}
+      {children}
+      {footerLeft === undefined && footerRight === undefined ? null : (
+        <footer data-page-footer-content>
+          {footerLeft === undefined ? null : <span data-page-footer-left>{footerLeft}</span>}
+          {footerRight === undefined ? null : <span data-page-footer-right>{footerRight}</span>}
+        </footer>
+      )}
+    </BasePage>
+  );
+}
+
+export function BaseBackCoverPage(props: BaseShellPageProps) {
+  return <BasePage {...props} footer={false} kind="back-cover" />;
+}
+
+export function BaseFigure({ caption, className, children, ...figureProps }: BaseFigureProps) {
+  return (
+    <figure {...figureProps} className={classNames("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={classNames("openpress-callout", className)} data-callout-kind={kind}>
+      {children}
+    </aside>
+  );
+}

package/src/openpress/core/index.tsx

@@ -0,0 +1,20 @@
+export {
+  BaseBackCoverPage,
+  BaseCallout,
+  BaseCoverPage,
+  BaseFigure,
+  BasePage,
+  BaseContentPage,
+  BaseTocPage,
+} from "./basePages";
+export type {
+  BaseCalloutKind,
+  BaseCalloutProps,
+  BaseFigureProps,
+  BasePageProps,
+  BaseContentPageProps,
+  BaseShellPageProps,
+  PageKind,
+  PageProps,
+  Manifest,
+} from "./types";

package/src/openpress/core/types.ts

@@ -0,0 +1,71 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+export type PageKind = "cover" | "toc" | "content" | "back-cover";
+
+export interface PageProps {
+  pageIndex: number;
+  totalPages: number;
+  chapterSlug?: string;
+  chapterTone?: string;
+  children: ReactNode;
+}
+
+export type BasePageProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+  kind: PageKind;
+  footer?: boolean;
+  children?: ReactNode;
+};
+
+export type BaseShellPageProps = Omit<BasePageProps, "kind" | "footer">;
+
+export type BaseContentPageProps = Omit<BasePageProps, "kind" | "footer" | "children"> &
+  PageProps & {
+    runningHeader?: ReactNode;
+    footerLeft?: ReactNode;
+    footerRight?: ReactNode;
+  };
+
+export type BaseFigureProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+  caption?: ReactNode;
+  children: ReactNode;
+};
+
+export type BaseCalloutKind = "info" | "warn" | "success" | "error" | (string & {});
+
+export type BaseCalloutProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+  kind?: BaseCalloutKind;
+  children: ReactNode;
+};
+
+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;
+  pdf?: {
+    filename?: string;
+  };
+  deploy?: {
+    adapter?: string;
+    source?: string;
+    projectName?: string;
+    commitDirty?: boolean;
+    requiresConfirmation?: boolean;
+  };
+  paths?: {
+    chaptersDir?: string;
+    sourceDir?: string;
+    componentsDir?: string;
+    mediaDir?: string;
+    themeDir?: string;
+    designDoc?: string;
+  };
+}

package/src/openpress/frameScheduler.ts

@@ -0,0 +1,32 @@
+type BrowserFrameCallback = (timestamp: number) => void;
+
+export function scheduleBrowserFrame(callback: BrowserFrameCallback) {
+  if (canUseAnimationFrame()) {
+    const frame = window.requestAnimationFrame(callback);
+    return () => window.cancelAnimationFrame(frame);
+  }
+
+  const timer = window.setTimeout(() => callback(now()), 0);
+  return () => window.clearTimeout(timer);
+}
+
+export function waitForBrowserFrame() {
+  return new Promise<void>((resolve) => {
+    scheduleBrowserFrame(() => resolve());
+  });
+}
+
+function canUseAnimationFrame() {
+  return (
+    typeof window !== "undefined" &&
+    typeof window.requestAnimationFrame === "function" &&
+    typeof document !== "undefined" &&
+    document.visibilityState !== "hidden"
+  );
+}
+
+function now() {
+  return typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+}