mosage 0.1.0 → 0.8.0

package/src/app/virtual.d.ts

@@ -0,0 +1,30 @@
+declare module 'virtual:mosage/docs' {
+  import type { DocModule } from './lib/sdk';
+
+  export const docIds: string[];
+  export const docCreatedAt: Record<string, number>;
+  export const docThemes: Record<string, string>;
+  export function loadDoc(id: string): Promise<DocModule>;
+}
+
+declare module 'virtual:mosage/themes' {
+  import type { ThemeDemoModule, ThemeMeta } from './lib/themes';
+
+  export const themes: ThemeMeta[];
+  export function loadThemeDemo(id: string): Promise<ThemeDemoModule>;
+}
+
+declare module 'virtual:mosage/folders' {
+  import type { FoldersManifest } from './lib/sdk';
+
+  const manifest: FoldersManifest;
+  export default manifest;
+}
+
+declare module 'virtual:mosage/config' {
+  import type { MoSageConfig } from '../config';
+
+  type ResolvedBuild = { showDocBrowser: boolean; allowHtmlExport: boolean };
+  const config: MoSageConfig & { build: ResolvedBuild; version: string };
+  export default config;
+}

package/template/AGENTS.md

@@ -0,0 +1,27 @@
+# MoSage workspace
+
+You author **documents** here — reports, proposals, whitepapers, memos. Each document is a folder under `docs/` with one `index.tsx` that exports an array of page components. Every page is one printed sheet (A4 by default).
+
+## Rules
+
+- Write only inside `docs/<id>/`. Don't touch `package.json`, `mosage.config.ts`, or other documents.
+- No new dependencies. Only `react`, `mosage`, and standard web APIs are available.
+- A document is one `index.tsx` plus an optional `assets/` folder. No sibling components files.
+
+## Skills
+
+| Skill | Use it for |
+| --- | --- |
+| `create-doc` | Drafting a new document end to end — scoping questions, page plan, then the file. |
+| `doc-authoring` | The technical reference: file contract, page canvas, print type scale, vertical budget, tables, TOC, page numbers. Read before any edit under `docs/`. |
+| `current-doc` | Resolving "this page" / "this element" — reads the cursor the dev server writes to `node_modules/.mosage/current.json`. |
+
+## Commands
+
+```bash
+pnpm dev       # dev server at http://localhost:5273
+pnpm build     # static site into dist/
+pnpm preview   # preview the build
+```
+
+In the viewer: outline sidebar, zoom, **PDF** export (true page size) and **HTML** export (self-contained).

package/template/README.md

@@ -0,0 +1,39 @@
+# 我的文件
+
+這個資料夾是一個 [MoSage](https://github.com/nickchen1998/MoSage) 專案：用 AI 寫文件，在瀏覽器裡預覽成真實的紙張，最後匯出 PDF、Word 或 HTML。
+
+## 開始
+
+```bash
+npm install        # 如果建立專案時跳過了安裝
+npm run dev        # 開啟 http://localhost:5273
+```
+
+在同一個資料夾開啟 Claude Code 或 Codex，描述你要的文件，例如「幫我寫一份 Q3 營運報告，給主管看，大約 6 頁」。
+AI 會用內建的 `create-doc` skill 先確認主題與資料來源，再規劃頁面、撰寫。
+
+## 資料夾
+
+```
+docs/
+  <文件代號>/
+    index.tsx      每份文件一個檔案，預設匯出頁面陣列
+    assets/        這份文件用到的圖片（選用）
+themes/            可重複使用的主題（選用）
+mosage.config.ts   專案設定
+```
+
+## 常用指令
+
+| 指令 | 說明 |
+| --- | --- |
+| `npm run dev` | 開啟檢視器，檔案一改就即時更新 |
+| `npx mosage check` | 找出超出紙張的內容、空白頁、落在頁尾的標題等問題 |
+| `npx mosage export <文件> --format docx` | 匯出 Word；也可以用 `pdf`、`html`、`png` |
+| `npx mosage import notes.md` | 把 Markdown 轉成一份文件 |
+| `npm run build` | 輸出靜態網站 |
+
+`check` 與 `export` 需要 Playwright：`npm i -D playwright && npx playwright install chromium`。
+在瀏覽器裡用右上角的 **Download** 匯出則不需要。
+
+升級 mosage 後，執行 `npx mosage sync:skills` 更新 `.agents/skills` 與 `.claude/skills`。

package/template/docs/getting-started/index.tsx

@@ -0,0 +1,230 @@
+import {
+  type DesignSystem,
+  type DocMeta,
+  type DocPage,
+  TableOfContents,
+  useDocPageCount,
+  useDocPageNumber,
+} from 'mosage';
+import type { CSSProperties, ReactNode } from 'react';
+
+export const design: DesignSystem = {
+  palette: {
+    bg: '#ffffff',
+    text: '#16181d',
+    muted: '#6b7280',
+    accent: '#1d4ed8',
+    rule: '#e4e7ec',
+  },
+  fonts: {
+    heading: '-apple-system, BlinkMacSystemFont, "Inter", system-ui, sans-serif',
+    body: '-apple-system, BlinkMacSystemFont, "Inter", system-ui, sans-serif',
+    mono: 'ui-monospace, "SF Mono", Menlo, monospace',
+  },
+  typeScale: { title: 44, h1: 28, h2: 20, h3: 16, body: 14, caption: 10 },
+  margin: 76,
+  leading: 1.55,
+  radius: 6,
+};
+
+const page: CSSProperties = {
+  width: '100%',
+  height: '100%',
+  boxSizing: 'border-box',
+  padding: 'var(--od-margin)',
+  background: 'var(--od-bg)',
+  color: 'var(--od-text)',
+  fontFamily: 'var(--od-font-body)',
+  fontSize: 'var(--od-size-body)',
+  lineHeight: 'var(--od-leading)',
+  position: 'relative',
+};
+
+const h1: CSSProperties = {
+  fontFamily: 'var(--od-font-heading)',
+  fontSize: 'var(--od-size-h1)',
+  lineHeight: 1.2,
+  fontWeight: 650,
+  letterSpacing: '-0.015em',
+  margin: '0 0 18px',
+};
+
+const h2: CSSProperties = {
+  fontFamily: 'var(--od-font-heading)',
+  fontSize: 'var(--od-size-h2)',
+  lineHeight: 1.25,
+  fontWeight: 600,
+  margin: '24px 0 10px',
+};
+
+const p: CSSProperties = { margin: '0 0 14px' };
+
+const Code = ({ children }: { children: ReactNode }) => (
+  <pre
+    style={{
+      fontFamily: 'var(--od-font-mono)',
+      fontSize: 11.5,
+      lineHeight: 1.55,
+      background: '#f6f7f9',
+      border: '1px solid var(--od-rule)',
+      borderRadius: 'var(--od-radius)',
+      padding: '12px 14px',
+      margin: '0 0 14px',
+      whiteSpace: 'pre-wrap',
+    }}
+  >
+    {children}
+  </pre>
+);
+
+const Footer = () => {
+  const n = useDocPageNumber();
+  const total = useDocPageCount();
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        left: 'var(--od-margin)',
+        right: 'var(--od-margin)',
+        bottom: 40,
+        display: 'flex',
+        justifyContent: 'space-between',
+        fontSize: 'var(--od-size-caption)',
+        color: 'var(--od-muted)',
+        borderTop: '1px solid var(--od-rule)',
+        paddingTop: 8,
+      }}
+    >
+      <span>Getting started with MoSage</span>
+      <span style={{ fontVariantNumeric: 'tabular-nums' }}>
+        {n} / {total}
+      </span>
+    </div>
+  );
+};
+
+const Cover: DocPage = () => (
+  <div style={{ ...page, display: 'flex', flexDirection: 'column', justifyContent: 'flex-end' }}>
+    <p
+      style={{
+        fontSize: 12,
+        letterSpacing: '0.18em',
+        textTransform: 'uppercase',
+        color: 'var(--od-accent)',
+        margin: '0 0 16px',
+      }}
+    >
+      mosage
+    </p>
+    <h1
+      data-od-outline="skip"
+      style={{ ...h1, fontSize: 'var(--od-size-title)', margin: '0 0 16px', maxWidth: 480 }}
+    >
+      Getting started
+    </h1>
+    <p style={{ ...p, fontSize: 15, color: 'var(--od-muted)', maxWidth: 460 }}>
+      Documents written as React. One component per printed page — the framework handles the sheet,
+      the outline, and the export.
+    </p>
+    <p style={{ ...p, marginTop: 40, fontSize: 11, color: 'var(--od-muted)' }}>
+      Delete this document once you've read it — it's just a starting point.
+    </p>
+  </div>
+);
+
+const Contents: DocPage = () => (
+  <div style={page}>
+    <h1 style={h1} data-od-outline="skip">
+      Contents
+    </h1>
+    <TableOfContents maxLevel={2} />
+    <p style={{ ...p, marginTop: 24, fontSize: 12, color: 'var(--od-muted)' }}>
+      This list is generated from the headings on the following pages. Page numbers update on their
+      own — never write a contents list by hand.
+    </p>
+    <Footer />
+  </div>
+);
+
+const HowItWorks: DocPage = () => (
+  <div style={page}>
+    <h1 style={h1}>How a document works</h1>
+    <p style={p}>
+      A document is a folder under <code>docs/</code> with a single <code>index.tsx</code>. It
+      default-exports an array of components — one per page, in order. There is no automatic reflow:
+      what you put on a page is exactly what lands on that sheet.
+    </p>
+
+    <Code>{`docs/
+  my-report/
+    index.tsx     // export default [Cover, Summary, …]
+    assets/       // optional images`}</Code>
+
+    <h2 style={h2}>The page canvas</h2>
+    <p style={p}>
+      A4 portrait is 794 × 1123 CSS pixels at 96dpi. With the default 76px margin, the text block is
+      642 × 971 — about 44 lines of body copy. Design in absolute pixels; the viewer only scales the
+      whole sheet.
+    </p>
+
+    <h2 style={h2}>Design tokens</h2>
+    <p style={p}>
+      The exported <code>design</code> const becomes CSS variables on every page:
+      <code> var(--od-bg)</code>, <code>var(--od-text)</code>, <code>var(--od-accent)</code>,
+      <code> var(--od-size-body)</code>, <code>var(--od-margin)</code>, and the rest. Change one
+      value and the whole document follows.
+    </p>
+
+    <Footer />
+  </div>
+);
+
+const Authoring: DocPage = () => (
+  <div style={page}>
+    <h1 style={h1}>Writing with an agent</h1>
+    <p style={p}>
+      This workspace ships with two skills. Ask your coding agent to draft a document and it runs
+      the <code>create-doc</code> workflow: scoping questions, a page plan, then the file.
+    </p>
+
+    <h2 style={h2}>Outline, contents, page numbers</h2>
+    <p style={p}>
+      Use real <code>h1</code>/<code>h2</code>/<code>h3</code> elements for section titles — the
+      framework scans them to build the sidebar outline and to fill{' '}
+      <code>&lt;TableOfContents /&gt;</code>. Page numbers come from <code>useDocPageNumber()</code>{' '}
+      and <code>useDocPageCount()</code>; never hardcode them.
+    </p>
+
+    <Code>{`import { useDocPageNumber, useDocPageCount } from 'mosage';
+
+const Footer = () => {
+  const n = useDocPageNumber();
+  const total = useDocPageCount();
+  return <span>{n} / {total}</span>;
+};`}</Code>
+
+    <h2 style={h2}>Exporting</h2>
+    <p style={p}>
+      <strong>PDF</strong> prints at the true page size — choose "Save as PDF" in the print dialog.
+      <strong> HTML</strong> downloads a self-contained copy (a zip when the document has assets).
+      Both wait for fonts and images, and both fill the contents list before serializing.
+    </p>
+
+    <h2 style={h2}>Next</h2>
+    <p style={p}>
+      Delete this folder, then ask your agent for the document you actually need. Everything the
+      agent has to know lives in the <code>doc-authoring</code> skill.
+    </p>
+
+    <Footer />
+  </div>
+);
+
+export const meta: DocMeta = {
+  title: 'Getting started',
+  subtitle: 'A tour of MoSage',
+  pageSize: 'A4',
+  createdAt: '2026-08-15T13:44:40.268Z',
+};
+
+export default [Cover, Contents, HowItWorks, Authoring] satisfies DocPage[];

package/template/mosage.config.ts

@@ -0,0 +1,5 @@
+import type { MoSageConfig } from 'mosage';
+
+const mosageConfig: MoSageConfig = {};
+
+export default mosageConfig;

package/template/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "workspace",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "mosage dev",
+    "build": "mosage build",
+    "preview": "mosage preview",
+    "check": "mosage check",
+    "export": "mosage export",
+    "sync:skills": "mosage sync:skills"
+  },
+  "dependencies": {
+    "mosage": "^0.1.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "vite": "^5.4.10"
+  }
+}

package/template/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["mosage/env"]
+  },
+  "include": ["docs/**/*", "mosage.config.ts"]
+}

package/README.en.md

@@ -1,57 +0,0 @@
-# MoSage
-
-[繁體中文](README.md) · **English**
-
-**A local workspace for writing books and theses with an AI.** Open the project folder in Claude Code,
-Codex or any agent that reads `AGENTS.md`, and work through kickoff, title and outline, drafting and
-revision in conversation. In the browser you read the manuscript typeset like a book, select text to
-leave notes for the AI, and accept or reject its suggested rewrites — then export the Word file your
-publisher or university asks for.
-
-```bash
-npx mosage init my-writing
-cd my-writing
-npm run dev        # http://localhost:5280
-claude             # or: codex — then say "開始" / "start" (or /kickoff)
-```
-
-No database, no account: everything is plain files (Markdown + YAML) in the project folder. Images and
-reference material are simply copied into it.
-
-## Highlights
-
-- **One project, many books** — each book or thesis lives in `books/<id>/` with its own settings, brief, style guide and chapters.
-- **Agent-led kickoff** — on a fresh project the agent interviews you (purpose, readers, voice, length), proposes titles and chapter structures, and scaffolds the outline.
-- **Outline board** — drag to reorder chapters, edit titles and summaries, track status per chapter.
-- **Book-like preview** — first-line indent, leading and fonts follow the Word export settings.
-- **Notes for the AI** — select any text and comment; notes are stored as `<!-- mosage:comment … -->` markers that the `apply-comments` skill processes.
-- **Suggestions you approve** — edits to existing prose arrive as `<!-- mosage:suggest … -->` markers shown as a diff with Accept / Reject.
-- **Live** — the page updates as the agent edits files.
-- **Automatic history** — every change snapshots the previous version; compare and restore in the UI.
-- **Where am I** — the UI writes `.mosage/current.json` so "make this paragraph shorter" just works.
-- **Word export** — real Word styles (Heading 1–4, body text, quote, caption), TOC field, page numbers, footnotes, tables, images; plus HTML (print to PDF) and merged Markdown.
-- **Import** — `mosage import manuscript.docx` splits an existing Word manuscript into chapters by heading style.
-
-## Commands
-
-| Command | |
-| --- | --- |
-| `npx mosage init <dir>` | Create a project |
-| `mosage dev` | Start the writing UI |
-| `mosage new <id> --title … --type book\|thesis` | Add a book |
-| `mosage status [book] [--json]` | Shelf overview / one book's chapters, words and pending markers |
-| `mosage export [book] [docx\|html\|md]` | Export to `output/<book>/` |
-| `mosage import <file.docx\|.md> [--book id]` | Import an existing manuscript |
-| `mosage sync-skills` | Refresh the agent skills after upgrading |
-
-## Credits
-
-The concepts — an `npx` scaffolder, agent skills shipped inside the workspace, browser comments applied
-by the agent, and a dev server that publishes the reader's position — come from
-[open-slide](https://github.com/open-slide/open-slide) by Yiwei Ho and
-[open-doc](https://github.com/simonliu-ai-product/open-doc) by Simon Liu (both MIT). MoSage is an
-independent implementation for long-form writing and Word delivery; it does not copy their code.
-
-## License
-
-[MIT](LICENSE)