@kanf/wema-kake 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 kan
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# wema-kake
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![License: ISC](https://img.shields.io/github/license/kan/wema-kake)](LICENSE)
+[![Last commit](https://img.shields.io/github/last-commit/kan/wema-kake)](https://github.com/kan/wema-kake/commits/main)
+[![@kanf/wema](https://img.shields.io/npm/v/%40kanf%2Fwema?label=%40kanf%2Fwema)](https://www.npmjs.com/package/@kanf/wema)
+[![Cloudflare Workers](https://img.shields.io/badge/Cloudflare-Workers-F38020?logo=cloudflareworkers&logoColor=white)](https://developers.cloudflare.com/workers/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![MCP](https://img.shields.io/badge/MCP-remote%20server-6E56CF)](https://modelcontextprotocol.io/)
+
+付箋を並べて書く Wiki です。1 ページが 1 枚のボードで、付箋を置き、線でつなぎ、ページの中に子ページを置いて整理します。Cloudflare Workers で動き、Claude などの LLM からも MCP で読み書きできます。
+
+![ページの画面。付箋と接続線、子ページの付箋が並んでいる](docs/images/page.png)
+
+**wema-kake はライブラリ（npm: `@kanf/wema-kake`）で、デプロイ物ではありません。** 使う人は、雛形から自分のリポジトリを作り、自分の Worker としてデプロイします。Wiki の処理と画面はパッケージにあり、手元に持つのは設定だけです。更新は `npm update` とデプロイで済みます。
+## 始め方
+
+```sh
+npx @kanf/wema-kake init my-wiki
+cd my-wiki
+npm run dev
+```
+
+`init` は、ディレクトリ、サイトの名前、既定の言語を聞いて、雛形を書き出します。`http://localhost:8787/` で開けます。
+
+雛形から GitHub のリポジトリを作ってデプロイするなら、Deploy to Cloudflare のボタンも使えます。
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/kan/wema-kake/tree/main/template)
+
+デプロイと、Cloudflare Access の設定の手順は、雛形の [README](template/README.md) にあります。**デプロイしただけでは、まだ使えません。** Access を設定するまで、画面と API は 500 を返します（保護のない状態で公開しないためです）。
+
+### 手元に持つもの
+
+| ファイル | 中身 |
+| --- | --- |
+| `src/config.ts` | サイトの名前、既定の言語、MCP を有効にするか、最初のページを作るか |
+| `wrangler.jsonc` | Worker の名前、バインディング、デプロイ先ごとの値（Access の設定、サイトのオリジン） |
+| `src/index.ts` | Worker の入口。設定を `@kanf/wema-kake` に渡すだけ |
+
+```ts
+// src/index.ts
+import { createWemaKake, PageDO } from '@kanf/wema-kake';
+import config from './config';
+
+export { PageDO };
+export default createWemaKake(config);
+```
+
+D1 のマイグレーションと画面は、`wrangler.jsonc` がパッケージの中（`node_modules/@kanf/wema-kake`）を直接指します。コピーしないので、更新で取り残されません。
+
+### 更新
+
+```sh
+npm update @kanf/wema-kake
+npm run deploy
+```
+
+`npm run deploy` は、D1 のマイグレーションを当ててから Worker をデプロイします。何を破壊的変更と呼び、版をまたいでデータをどう引き継ぐかは、[docs/package.md](docs/package.md) に書いてあります。
+
+## できること
+
+- 付箋を置く、動かす、色を付ける、線でつなぐ。箇条書き、チェックリスト、画像、リンクを書ける
+- 複数のブラウザで同じページを開くと、変更がその場で反映される
+- ページの中に子ページを置ける。子ページは、中の付箋の配置を縮小した図つきの付箋として表示され、押すとズームして入る
+- ページの一覧もボードで、ページが付箋、ページ間のリンクが線になる。全文検索で絞り込める
+- リモート MCP サーバーを備えていて、claude.ai のコネクタとして登録できる。LLM がボードを読み、付箋を足し、整理する
+- LLM の操作は、操作の単位で記録される。ページの画面から、まとめて取り消せる
+
+## wema との関係
+
+名前は、神社で絵馬を掛ける場所「絵馬掛（えまかけ）」から来ています。wema が絵馬、wema-kake がそれを掛ける場所です。
+
+ボードの表示と編集は、付箋ボードのライブラリ [wema](https://github.com/kan/wema)（npm: [`@kanf/wema`](https://www.npmjs.com/package/@kanf/wema)）が受け持ちます。wema は、ブラウザの中だけで動くライブラリです。保存先や同期の仕組みは持ちません。
+
+wema-kake は、wema に次のものを足して Wiki にしたものです。
+
+| wema が受け持つ | wema-kake が足す |
+| --- | --- |
+| 付箋と接続線の表示と編集 | ページという単位と、ページ間のリンク、ページの階層 |
+| Undo / Redo、パンとズーム | サーバーへの保存と、複数のブラウザの間の同期 |
+| 変更の内容を表すデータ（デルタ） | 全文検索、画像の保存、認証 |
+| | LLM 向けの MCP サーバーと、その操作の取り消し |
+
+wema の側に要る機能は、wema へ依頼して入れてもらい、その版を取り込んでいます。使っている wema の版は、`package.json` の `dependencies` にあります。
+
+## 構成
+
+| 役割 | 使っているもの |
+| --- | --- |
+| サーバー | Cloudflare Workers + [Hono](https://hono.dev/) |
+| ページの内容と同期 | Durable Objects（1 ページ = 1 オブジェクト、SQLite、WebSocket） |
+| ページの一覧と全文検索 | D1 |
+| 画像 | R2 |
+| 認証 | Cloudflare Access |
+| LLM との連携 | リモート MCP（認可は、Access の Managed OAuth） |
+
+## このリポジトリでの開発
+
+```sh
+npm install
+cp .dev.vars.example .dev.vars
+npx wrangler d1 migrations apply DB --local
+npm run dev
+```
+
+`http://localhost:8787/` で開けます。ローカルでは Access を通らず、`.dev.vars` の `DEV_USER_EMAIL` が利用者になります。リポジトリの中の利用側（`dev/`）が、ビルドせずに `src/` を使います。
+
+| コマンド | 内容 |
+| --- | --- |
+| `npm run dev` | 画面をビルドして、ローカルのサーバーを起動する |
+| `npm run dev:roji` | 同じサーバーを、[roji](https://github.com/kan/roji)（1.5.0 以降）を通して起動する。空いているポートを使い、`https://wema-kake.<roji のドメイン>` で開ける |
+| `npm test` | テストを実行する（Workers のランタイムの上で動く） |
+| `npm run lint` | 型チェック |
+| `npm run build` | 配るものを作る。画面（`dist/web`）と Worker の側（`dist/lib`） |
+| `npm pack` | パッケージを作る（`prepack` が `build` を回す） |
+
+## 文書
+
+- [docs/package.md](docs/package.md): パッケージの入口、設定、互換の決まり
+- [AGENTS.md](AGENTS.md): 設計と、実装で守る決まり。コーディングエージェント向けの指示を兼ねる
+- [docs/plan.md](docs/plan.md): 実装の計画と、フェーズごとの記録
+
+## ライセンス
+
+[ISC](LICENSE)

package/bin/wema-kake.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// wema-kake の入口のコマンド。今あるのは init だけ。
+//
+//   npx @kanf/wema-kake init [directory] [--yes] [--no-install]
+//
+// Wiki 1 つ分のディレクトリを作る。中身は、パッケージに同梱した template/ で、聞いた値を
+// src/config.ts と wrangler.jsonc と package.json に埋めてから書き出す。
+//
+// 雛形は GitHub から取らず、同梱のものを使う。init が作るのは、その版の wema-kake に合った雛形になる。
+// 依存は足さない（対話は node:readline/promises で足りる）
+import { spawn } from 'node:child_process';
+import { cp, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import process from 'node:process';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const template = join(root, 'template');
+const LANGS = ['ja', 'en'];
+
+const USAGE = `usage: npx @kanf/wema-kake init [directory] [--yes] [--no-install]
+
+  init          create a wiki in a new directory
+  --yes, -y     take every default without asking
+  --no-install  write the files and stop, without running npm install
+`;
+
+function fail(reason) {
+  console.error(`wema-kake: ${reason}`);
+  process.exit(1);
+}
+
+const argv = process.argv.slice(2);
+if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+  process.stdout.write(USAGE);
+  process.exit(argv.length === 0 ? 1 : 0);
+}
+if (argv[0] !== 'init') fail(`unknown command: ${argv[0]}\n\n${USAGE}`);
+
+const useDefaults = argv.includes('--yes') || argv.includes('-y');
+const skipInstall = argv.includes('--no-install');
+const positional = argv.slice(1).find((arg) => !arg.startsWith('-'));
+
+// 聞ける相手がいないなら、既定の値で進めない。readline は端末でないとき、質問を出す前に入力を
+// 読み切って閉じるので、パイプで答えを流す形は支えない。黙って既定の値で作るより、--yes を促して落ちる
+if (!useDefaults && !process.stdin.isTTY) fail('no terminal to ask on. Pass --yes to take every default.');
+
+await init();
+
+async function init() {
+  const rl = useDefaults ? null : createInterface({ input: process.stdin, output: process.stdout });
+  rl?.on('SIGINT', cancel);
+  const ask = async (question, fallback) => {
+    if (rl === null) return fallback;
+    const answer = (await rl.question(`${question} (${fallback}) `).catch(cancel)).trim();
+    return answer === '' ? fallback : answer;
+  };
+
+  try {
+    const directory = positional ?? (await ask('Directory', 'my-wiki'));
+    const target = resolve(process.cwd(), directory);
+    await checkEmpty(target, directory);
+
+    // Worker、D1、R2 の名前は、ディレクトリ名（パスの最後の部分）から作る
+    const slug = slugify(basename(target));
+    const siteName = await ask('Site name', 'My wiki');
+    let defaultLang;
+    for (;;) {
+      defaultLang = await ask(`Default language (${LANGS.join(' / ')})`, 'en');
+      if (LANGS.includes(defaultLang)) break;
+      // --yes では同じ既定の値が返り続けるので、回り続けない
+      if (rl === null) fail(`unknown language: ${defaultLang}`);
+      process.stdout.write(`  choose one of ${LANGS.join(', ')}\n`);
+    }
+
+    await cp(template, target, { recursive: true, filter: packableOnly });
+    await restoreGitignore(target);
+    await fill(target, { slug, siteName, defaultLang });
+    // ローカル開発の主体。.dev.vars は .gitignore に入っている
+    await cp(join(target, '.dev.vars.example'), join(target, '.dev.vars'));
+
+    process.stdout.write(`\nCreated ${target}\n`);
+    const install = skipInstall
+      ? false
+      : (await ask('Install dependencies now? (y/n)', 'y')).toLowerCase().startsWith('y');
+    rl?.close();
+    if (install) await npmInstall(target);
+    printNextSteps(directory, install);
+  } finally {
+    rl?.close();
+  }
+}
+
+/** 雛形に値を埋める。埋める場所は 1 つずつ名指しする（replaceOnce が見つからなければ落ちる） */
+async function fill(target, { slug, siteName, defaultLang }) {
+  await replaceEach(join(target, 'src', 'config.ts'), [
+    ["  siteName: 'My wiki',", `  siteName: ${quote(siteName)},`],
+    ["  defaultLang: 'en',", `  defaultLang: ${quote(defaultLang)},`],
+  ]);
+
+  await replaceEach(join(target, 'wrangler.jsonc'), [
+    ['"name": "my-wiki",', `"name": "${slug}",`],
+    ['"database_name": "my-wiki",', `"database_name": "${slug}",`],
+    ['"bucket_name": "my-wiki-images"', `"bucket_name": "${slug}-images"`],
+    ['https://my-wiki.<account>', `https://${slug}.<account>`],
+  ]);
+
+  // 自分と同じ版を指す。雛形に書いてある範囲は、雛形を直したときのものなので、古い版を指しうる。
+  // 今の範囲を雛形から読んでから、名指しで置き換える（正規表現で当てると、書き方が変わった日に
+  // 0 件の置き換えで素通りする）
+  const manifest = join(target, 'package.json');
+  const current = JSON.parse(await readFile(manifest, 'utf8')).dependencies['@kanf/wema-kake'];
+  await replaceEach(manifest, [
+    ['"name": "my-wiki",', `"name": "${slug}",`],
+    [`"@kanf/wema-kake": "${current}"`, `"@kanf/wema-kake": "^${await version()}"`],
+  ]);
+
+  await replaceEach(join(target, 'README.md'), [['# my-wiki', `# ${siteName}`]]);
+}
+
+/** ファイルの中の `[from, to]` を、順に 1 か所ずつ置き換える */
+async function replaceEach(path, pairs) {
+  const source = await readFile(path, 'utf8');
+  await writeFile(path, pairs.reduce((text, [from, to]) => replaceOnce(text, from, to), source));
+}
+
+async function npmInstall(target) {
+  process.stdout.write('\n');
+  const code = await new Promise((done) => {
+    const npm = spawn('npm', ['install'], { cwd: target, stdio: 'inherit', shell: process.platform === 'win32' });
+    npm.on('error', () => done(1));
+    npm.on('close', (status) => done(status ?? 1));
+  });
+  if (code !== 0) fail('npm install failed. Run it yourself in the new directory.');
+}
+
+function printNextSteps(directory, installed) {
+  // 空白などを含む名前は、そのまま貼り付けて通るように引用符で囲む
+  const cd = /^[\w./-]+$/.test(directory) ? directory : `'${directory.replaceAll("'", "'\\''")}'`;
+  const steps = [`cd ${cd}`, ...(installed ? [] : ['npm install']), 'npm run dev   # http://localhost:8787'];
+  process.stdout.write(`\nNext:\n\n${steps.map((step) => `  ${step}`).join('\n')}
+
+To deploy:
+
+  npx wrangler login
+  npm run deploy:first
+
+Then set up Cloudflare Access ("Access の設定" in the README). Until then the wiki answers 500.\n`);
+}
+
+/**
+ * 空でないディレクトリには書かない。上書きの意味が人によって違うので、ここで止める。
+ * ディレクトリはまだ作らない（質問の途中で抜けたときに、空のディレクトリを残さない）。書き出す cp が作る
+ */
+async function checkEmpty(target, directory) {
+  let entries;
+  try {
+    entries = await readdir(target);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') fail(`cannot write to ${directory} (${error instanceof Error ? error.message : error})`);
+    return;
+  }
+  if (entries.length > 0) fail(`${directory} is not empty`);
+}
+
+/**
+ * 無視の設定を .gitignore に戻す。npm は .gitignore をパッケージに入れないので、配るときは
+ * gitignore という名前の複製を入れてある（scripts/pack-template.mjs）。repo から直に走らせたときは
+ * .gitignore がそのまま来るので、何もしない
+ */
+async function restoreGitignore(target) {
+  const ignore = join(target, '.gitignore');
+  try {
+    await rename(join(target, 'gitignore'), ignore);
+  } catch {
+    // 複製がないのは、repo から走らせたとき（.gitignore がある）か、prepack を通していない tarball
+    // から走らせたとき。後者を黙って通すと、無視の設定がない木ができる
+    await stat(ignore).catch(() => fail('the template has no .gitignore (was it packed without prepack?)'));
+  }
+}
+
+/** 生成物と手元の物は持っていかない（repo から直に走らせたときのため） */
+function packableOnly(source) {
+  return !/[\\/](node_modules|\.wrangler|package-lock\.json|\.dev\.vars|worker-configuration\.d\.ts)$/.test(source);
+}
+
+/** 1 か所だけ置き換える。見つからないか、2 か所以上あれば落とす（雛形を直した日に黙って素通りしない） */
+function replaceOnce(source, from, to) {
+  const at = source.indexOf(from);
+  if (at === -1) fail(`the template no longer contains: ${from}`);
+  if (source.indexOf(from, at + from.length) !== -1) fail(`the template repeats: ${from}`);
+  return `${source.slice(0, at)}${to}${source.slice(at + from.length)}`;
+}
+
+/** TypeScript の文字列として書ける形にする */
+function quote(value) {
+  return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`;
+}
+
+/** Worker、D1、R2 の名前に使える形 */
+function slugify(name) {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .slice(0, 54)
+    // 切り詰めた後に削る（先に削ると、切った位置の `-` が末尾に残る。Worker の名前は `-` で終われない）
+    .replace(/^-+|-+$/g, '');
+  return slug === '' ? 'my-wiki' : slug;
+}
+
+async function version() {
+  return JSON.parse(await readFile(join(root, 'package.json'), 'utf8')).version;
+}
+
+/** 途中で抜けた人向け。失敗ではないので、理由を並べずに終わる */
+function cancel() {
+  process.stdout.write('\ncancelled\n');
+  process.exit(130);
+}

package/dist/lib/index.d.ts

@@ -0,0 +1,13 @@
+import type { WemaKakeConfig, WemaKakeEnv } from './worker/config';
+export type { Lang } from './shared/i18n';
+export type { WemaKakeConfig, WemaKakeEnv } from './worker/config';
+/**
+ * ページごとの Durable Object。**利用側の Worker の入口から、この名前で再 export すること**
+ * （Durable Object のクラスは、Worker の入口から export されている必要がある）。
+ * クラス名は、利用側の `wrangler.jsonc`（`durable_objects` と `migrations`）にも書かれる
+ */
+export { PageDO } from './worker/page-do';
+/**
+ * Worker の入口（`export default` にするもの）を作る。設定の不正は、ここで例外にする
+ */
+export declare function createWemaKake(config?: WemaKakeConfig): ExportedHandler<WemaKakeEnv>;

package/dist/lib/index.js

@@ -0,0 +1,14 @@
+import { createApp } from './worker/index';
+/**
+ * ページごとの Durable Object。**利用側の Worker の入口から、この名前で再 export すること**
+ * （Durable Object のクラスは、Worker の入口から export されている必要がある）。
+ * クラス名は、利用側の `wrangler.jsonc`（`durable_objects` と `migrations`）にも書かれる
+ */
+export { PageDO } from './worker/page-do';
+/**
+ * Worker の入口（`export default` にするもの）を作る。設定の不正は、ここで例外にする
+ */
+export function createWemaKake(config = {}) {
+    const app = createApp(config);
+    return { fetch: (request, env, ctx) => app.fetch(request, env, ctx) };
+}

package/dist/lib/shared/api.d.ts

@@ -0,0 +1,97 @@
+/** ページの一覧で 1 回に返す件数の上限 */
+export declare const MAX_LIST_LIMIT = 500;
+/** ページを変更してから、D1 の索引へ反映するまでの時間 */
+export declare const INDEX_DELAY_MS = 5000;
+/** 表示名の長さの上限 */
+export declare const MAX_TITLE_LENGTH = 200;
+/**
+ * ページに付けられる色。wema の付箋の色と同じ並び（子ページの付箋と、一覧の付箋の色になる）。
+ * 付けていないページは null
+ */
+export declare const PAGE_COLORS: readonly ['#FFF9C4', '#FFCDD2', '#FFE0B2', '#E1BEE7', '#BBDEFB', '#B2DFDB', '#C8E6C9', '#F5F5F5'];
+export type PageColor = (typeof PAGE_COLORS)[number];
+/** 色を付けていないページの、付箋（子ページの付箋、一覧の付箋）の色 */
+export declare const UNSET_PAGE_COLOR: PageColor;
+/** 検索語の長さの上限 */
+export declare const MAX_QUERY_LENGTH = 200;
+/** 1 人が付けられるブックマークの数 */
+export declare const MAX_BOOKMARKS = 100;
+/**
+ * 一覧のボードの付箋に出す、本文の冒頭の長さ（文字数）。
+ * 付箋の大きさ（src/web/index-board.ts）に収まる量にしてある
+ */
+export declare const INDEX_EXCERPT_LENGTH = 60;
+/** `GET /api/index` が返すページ */
+export interface IndexPage {
+    name: string;
+    title: string | null;
+    /** ページの色（PAGE_COLORS のどれか）。付けていなければ null */
+    color: string | null;
+    note_count: number;
+    updated_at: number;
+    /** 本文の冒頭（INDEX_EXCERPT_LENGTH 文字まで） */
+    excerpt: string;
+    /** 直接の子ページの数 */
+    child_count: number;
+}
+/** `POST /api/pages-info` が返す、ページの概要（子ページの付箋の表示に使う） */
+export interface PageSummary {
+    name: string;
+    title: string | null;
+    /** ページの色（PAGE_COLORS のどれか）。付けていなければ null */
+    color: string | null;
+    note_count: number;
+    /** 親ページのスラッグ。ルートのページなら null */
+    parent: string | null;
+    /** 付箋の配置（`[[x, y, 幅, 高さ, 色], ...]` の JSON）。索引がまだなら null */
+    layout: string | null;
+}
+/** `GET /api/search?roots=1` が返す、一致したページと、そのルート */
+export interface RootHit {
+    /** 一致したページ */
+    name: string;
+    /** そのページのルート。ルートのページ自身が一致したなら、`name` と同じ */
+    root: string;
+}
+/** `GET /api/index` が返すリンク */
+export interface IndexLink {
+    from_page: string;
+    to_page: string;
+    /** リンク先のページがまだ作られていなければ 1 */
+    missing: number;
+}
+/** 記録済みの操作 1 件の概要（一覧に出すもの） */
+export interface OpSummary {
+    seq: number;
+    actor: string;
+    summary: string | null;
+    /** この操作が取り消しなら、取り消した対象の seq。取り消しでなければ null */
+    reverts: number | null;
+    /** この操作を取り消した操作の seq。取り消されていなければ null */
+    revertedBy: number | null;
+    createdAt: number;
+}
+/**
+ * 取り消さなかった理由。
+ * - modified: その後に変更されていた（一部のフィールドだけ変更されていた場合は、残りは取り消している）
+ * - connected: 付箋の作成を取り消そうとしたが、取り消さない接続線がつながっている
+ * - deleted: 更新を取り消そうとしたが、対象がもうない
+ * - exists: 削除を取り消そうとしたが、同じ id のものがある
+ * - endpoint-missing: 接続線の削除を取り消そうとしたが、両端の付箋がない
+ */
+export type SkipReason = 'modified' | 'connected' | 'deleted' | 'exists' | 'endpoint-missing';
+/** 取り消さなかったものと、その理由 */
+export interface Skipped {
+    target: 'note' | 'edge';
+    id: string;
+    reason: SkipReason;
+}
+/** 取り消しの結果 */
+export interface RevertOutcome {
+    /** 取り消しとして記録した操作の seq。取り消せるものが 1 つもなかった場合は null */
+    seq: number | null;
+    /** 取り消したデルタの数 */
+    applied: number;
+    /** その後に変更されていたなどの理由で、取り消さなかったもの */
+    skipped: Skipped[];
+}

package/dist/lib/shared/api.js

@@ -0,0 +1,23 @@
+// サーバーとブラウザの両方が使う、HTTP API と DO のメソッドの型と定数。
+/** ページの一覧で 1 回に返す件数の上限 */
+export const MAX_LIST_LIMIT = 500;
+/** ページを変更してから、D1 の索引へ反映するまでの時間 */
+export const INDEX_DELAY_MS = 5000;
+/** 表示名の長さの上限 */
+export const MAX_TITLE_LENGTH = 200;
+/**
+ * ページに付けられる色。wema の付箋の色と同じ並び（子ページの付箋と、一覧の付箋の色になる）。
+ * 付けていないページは null
+ */
+export const PAGE_COLORS = ['#FFF9C4', '#FFCDD2', '#FFE0B2', '#E1BEE7', '#BBDEFB', '#B2DFDB', '#C8E6C9', '#F5F5F5'];
+/** 色を付けていないページの、付箋（子ページの付箋、一覧の付箋）の色 */
+export const UNSET_PAGE_COLOR = '#FFF9C4';
+/** 検索語の長さの上限 */
+export const MAX_QUERY_LENGTH = 200;
+/** 1 人が付けられるブックマークの数 */
+export const MAX_BOOKMARKS = 100;
+/**
+ * 一覧のボードの付箋に出す、本文の冒頭の長さ（文字数）。
+ * 付箋の大きさ（src/web/index-board.ts）に収まる量にしてある
+ */
+export const INDEX_EXCERPT_LENGTH = 60;

package/dist/lib/shared/delta.d.ts

@@ -0,0 +1,24 @@
+import type { HistoryDelta, WemaBoardData, WemaEdge, WemaNote } from '@kanf/wema';
+import type { NoteInfos } from './note-info';
+export type { HistoryDelta, WemaEdge, WemaNote };
+/** 操作を打ち消すデルタ。逆順にし、作成と削除、before と after を入れ替える */
+export declare function invertDeltas(deltas: HistoryDelta[]): HistoryDelta[];
+/** viewport は各クライアントの表示状態なので保存しない */
+export type BoardData = Omit<WemaBoardData, 'viewport'>;
+/** 付箋と接続線の一部（拒否したときに返す現在値など） */
+export type BoardContent = Pick<BoardData, 'notes' | 'edges'>;
+export interface Snapshot {
+    seq: number;
+    /** 表示名。未設定なら null（表示にはスラッグを使う） */
+    title: string | null;
+    /** ページの色（PAGE_COLORS のどれか）。付けていなければ null */
+    color: string | null;
+    /**
+     * ページを作るたびに変わる値。まだ作られていなければ null。
+     * 削除して作り直したページを、前のページと見分けるのに使う
+     */
+    epoch: string | null;
+    data: BoardData;
+    /** 付箋ごとの付加情報（作成者、更新日時）。`data` の付箋と同じ id を持つ */
+    info: NoteInfos;
+}

package/dist/lib/shared/delta.js

@@ -0,0 +1,19 @@
+/** 操作を打ち消すデルタ。逆順にし、作成と削除、before と after を入れ替える */
+export function invertDeltas(deltas) {
+    return [...deltas].reverse().map((d) => {
+        switch (d.type) {
+            case 'note:create':
+                return { type: 'note:delete', note: d.note };
+            case 'note:delete':
+                return { type: 'note:create', note: d.note };
+            case 'edge:create':
+                return { type: 'edge:delete', edge: d.edge };
+            case 'edge:delete':
+                return { type: 'edge:create', edge: d.edge };
+            case 'note:update':
+                return { type: d.type, noteId: d.noteId, before: d.after, after: d.before };
+            case 'edge:update':
+                return { type: d.type, edgeId: d.edgeId, before: d.after, after: d.before };
+        }
+    });
+}

package/dist/lib/shared/guide.d.ts

@@ -0,0 +1,32 @@
+import type { BoardContent } from './delta';
+import type { Lang } from './i18n';
+/** 最初のページのスラッグ */
+export declare const FIRST_PAGE_SLUG = "first-page";
+/** 付箋の名前。接続線が指す名前で、付箋の id にもなる */
+type Key = 'sample' | 'intro' | 'notes' | 'text' | 'edges' | 'view' | 'pages' | 'llm';
+/** 1 つの言語の文面 */
+interface GuideText {
+    /** 最初のページの表示名 */
+    firstPageTitle: string;
+    /** 案内の付箋。最初のページ用と、使い方のボード用 */
+    intro: {
+        first: string;
+        help: string;
+    };
+    /** 本文の装飾の見本 */
+    sample: string;
+    /** 見出しと、項目の並び */
+    sections: Record<Exclude<Key, 'sample' | 'intro'>, [heading: string, items: string[]]>;
+    /**
+     * 列の間隔。付箋は autoSize なので、幅は最も長い行で決まる。**長い行を足すと、隣の付箋と重なる。**
+     * 1 行を短く保つか、ここを広げる
+     */
+    column: number;
+}
+/** 最初のページの表示名 */
+export declare const firstPageTitle: (lang: Lang) => string;
+/** 案内の付箋の id。付箋を縦に積む画面で、先頭に並べるのに使う（src/web/stacked-view.ts） */
+export declare const GUIDE_INTRO_ID: string;
+/** 使い方の付箋と接続線。`intro` で、案内の付箋の文面を選ぶ */
+export declare function guideBoard(intro: keyof GuideText['intro'], lang: Lang): BoardContent;
+export {};