@ampless/plugin-reading-time 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ampless contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,94 @@
+> English: [README.md](./README.md)
+>
+
+# @ampless/plugin-reading-time
+
+[ampless](https://github.com/heavymoons/ampless) 向け読了時間バッジプラグイン。投稿本文のテキストから読了時間を推定し、本文の前後に設定可能なラベルを挿入します。
+
+> **プレリリース / アルファ版。** v1.0 まではマイナーバージョンでも破壊的変更が入る可能性があります。
+
+バッジは `publicHtmlForPost` capability（Phase 6d）経由で出力されます。`ampless.publicHtmlForPost(post)` を呼ぶテーマなら自動的に描画されます。HTML はランタイムが `sanitize-html` で strict allowlist に沿ってサニタイズするため、テーマ側で `dangerouslySetInnerHTML` を使う必要はありません。
+
+AWS のデータ権限は不要です。すべて公開 Next.js プロセスのリクエスト時に動作します。`trust_level` は `untrusted`。
+
+## インストール
+
+```bash
+npm install @ampless/plugin-reading-time@alpha
+```
+
+## 設定
+
+`cms.config.ts` に記述します:
+
+```ts
+import { defineConfig } from 'ampless'
+import readingTimePlugin from '@ampless/plugin-reading-time'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    readingTimePlugin(),
+  ],
+})
+```
+
+| オプション | デフォルト | 備考 |
+|---|---|---|
+| `wordsPerMinute` | `200` | 想定読書速度。英語の成人平均は 200〜250 WPM。 |
+| `labelTemplate` | `'{minutes} min read'` | ラベルのテンプレート。`{minutes}` と `{words}` プレースホルダーを使用可能。 |
+| `position` | `'beforeContent'` | `'beforeContent'` または `'afterContent'`。 |
+| `instanceId` | `'reading-time'` | ランタイムのキー解決に使う namespace。同じサイトで 2 回登録する場合のみ変更する。 |
+
+すべてのオプションはデプロイなしで `/admin/plugins → 読了時間` から編集できます。コンストラクタの値は初期デフォルトに過ぎません。
+
+## 設定項目（管理画面）
+
+`/admin/plugins → 読了時間` から設定できます:
+
+| キー | 型 | デフォルト | 備考 |
+|---|---|---|---|
+| `wordsPerMinute` | number | `200` | 最小 50、最大 1000。読書速度の仮定値。 |
+| `labelTemplate` | text | `'{minutes} min read'` | `{minutes}` と `{words}` をプレースホルダーとして使用可能。最大 200 文字。 |
+| `position` | select | `'beforeContent'` | `'beforeContent'` / `'afterContent'`。 |
+
+## 出力 HTML
+
+プラグインは単一の `<p>` 要素を出力します:
+
+```html
+<p class="ampless-reading-time" data-words="480" data-minutes="3">3 min read</p>
+```
+
+- `data-words` — 生の語数（CJK 正規化後）。
+- `data-minutes` — 推定読了時間（分）。常に 1 以上。
+- クラス名 `ampless-reading-time` は安定しており、CSS によるスタイリングに利用できます。
+
+## 語数カウント
+
+- **英語:** 空白区切りのトークン数。
+- **CJK 文字**（漢字・ひらがな・カタカナ）: 独立してカウントし、2 で除算して英語 WPM に合わせた換算値を算出。具体的には `CJK 文字数 / 2` の reading units を英語語数に加算します。
+- **複合言語の投稿**: 両方のカウントを合算します。
+
+フォーマット別テキスト抽出:
+
+| `post.format` | テキスト抽出方法 |
+|---|---|
+| `tiptap` | JSON ツリーを再帰的に走査し、`text` ノードの値を結合。 |
+| `markdown` | fenced code、インラインコード、画像・リンク構文、太字・斜体マーカー、HTML タグを除去。 |
+| `html` | HTML タグを除去。 |
+| `static` | 空文字を返す — バッジは出力されない。 |
+
+## ラベルの escape
+
+ラベル文字列はプレースホルダー置換後に HTML escape されます。`< > & " '` は `&lt; &gt; &amp; &quot; &#39;` に変換されるため、管理画面の `labelTemplate` 設定に不等号が含まれていても XSS は発生しません。
+
+## トラストレベル
+
+`untrusted`。`@ampless/runtime` が検証・サニタイズする HTML descriptor を返すだけです。DynamoDB、S3、Lambda プロセッサーには一切触れません。
+
+## v1 では対応しないこと
+
+- **テーマ CSS** — `<p>` 要素には安定したクラス名（`ampless-reading-time`）が付与されるのでテーマ側でスタイリングできます。デフォルト CSS は注入しません。
+- **ロケール別ラベル** — `labelTemplate` は全ロケール共通の単一文字列です。多言語サイトでは `instanceId` を別にしてプラグインを 2 回登録し、テーマ側でスロットを条件分岐させることで対応できます。
+- **文字種別 WPM のカスタマイズ** — `wordsPerMinute` 設定は一律適用されます。アラビア語とラテン語で別レートを設定するなど、文字種別の細かな調整は deferred です。

package/README.md

@@ -0,0 +1,94 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+>
+
+# @ampless/plugin-reading-time
+
+Reading-time badge plugin for [ampless](https://github.com/heavymoons/ampless). Estimates the reading time of a post from its body text and injects a configurable label before or after the post content.
+
+> **Pre-release / alpha.** Breaking changes possible in any minor version until v1.0.
+
+The badge is emitted via the `publicHtmlForPost` capability (Phase 6d). Themes that call `ampless.publicHtmlForPost(post)` automatically render it. The runtime sanitizes the HTML with `sanitize-html` under a strict allowlist before it reaches the page — no `dangerouslySetInnerHTML` needed in the theme.
+
+No AWS data permissions are required — everything runs at request time inside the public Next.js process. The plugin's `trust_level` is `untrusted`.
+
+## Install
+
+```bash
+npm install @ampless/plugin-reading-time@alpha
+```
+
+## Configure
+
+In `cms.config.ts`:
+
+```ts
+import { defineConfig } from 'ampless'
+import readingTimePlugin from '@ampless/plugin-reading-time'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    readingTimePlugin(),
+  ],
+})
+```
+
+| Option | Default | Notes |
+|---|---|---|
+| `wordsPerMinute` | `200` | Assumed reading speed. Typical adult reading speed is 200–250 WPM for English. |
+| `labelTemplate` | `'{minutes} min read'` | Template for the label. Supports `{minutes}` and `{words}` placeholders. |
+| `position` | `'beforeContent'` | `'beforeContent'` or `'afterContent'`. |
+| `instanceId` | `'reading-time'` | Namespace used for runtime key resolution. Change only if registering the plugin twice. |
+
+All options are also editable from `/admin/plugins → Reading time` without a redeploy — the constructor values above are just the initial defaults.
+
+## Settings (admin UI)
+
+Configure from `/admin/plugins → Reading time`:
+
+| Key | Type | Default | Notes |
+|---|---|---|---|
+| `wordsPerMinute` | number | `200` | Min 50, max 1000. Reading speed assumption. |
+| `labelTemplate` | text | `'{minutes} min read'` | Use `{minutes}` and `{words}` as placeholders. Max 200 chars. |
+| `position` | select | `'beforeContent'` | `'beforeContent'` / `'afterContent'`. |
+
+## Output HTML
+
+The plugin emits a single `<p>` element:
+
+```html
+<p class="ampless-reading-time" data-words="480" data-minutes="3">3 min read</p>
+```
+
+- `data-words` — raw word count (after CJK normalization).
+- `data-minutes` — computed reading time in minutes (always ≥ 1).
+- The class `ampless-reading-time` is stable and suitable for CSS targeting.
+
+## Word counting
+
+- **English:** whitespace-separated tokens.
+- **CJK characters** (Han, Hiragana, Katakana): counted separately and divided by 2 to roughly match per-minute reading rates. Specifically: `CJK_chars / 2` reading units are added to the English word count.
+- **Mixed language posts** combine both counts.
+
+Format handling:
+
+| `post.format` | How text is extracted |
+|---|---|
+| `tiptap` | Recursively walks the JSON tree, collecting `text` node values. |
+| `markdown` | Strips fenced code, inline code, images, links syntax, bold/italic markers, and HTML tags. |
+| `html` | Strips HTML tags. |
+| `static` | Returns empty — no badge rendered. |
+
+## Label escaping
+
+The label string is HTML-escaped after placeholder substitution. Characters `< > & " '` become `&lt; &gt; &amp; &quot; &#39;` respectively, preventing XSS even when a site operator stores angle brackets in the `labelTemplate` admin setting.
+
+## Trust level
+
+`untrusted`. The plugin only emits an HTML descriptor validated and sanitized by `@ampless/runtime`. It does not access DynamoDB, S3, or any Lambda processor.
+
+## What it does not do (v1)
+
+- **Theme CSS** — The `<p>` element carries a stable class name (`ampless-reading-time`) for theme authors to style. No default CSS is injected.
+- **Locale-aware labels** — The `labelTemplate` is a single string shared across all locales. Multi-locale setups can register the plugin twice with distinct `instanceId` values and theme-side conditionally render the correct slot.
+- **Custom WPM per script** — The `wordsPerMinute` setting applies uniformly. Fine-grained per-script tuning (e.g. different rates for Arabic vs. Latin) is deferred.

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+import { AmplessPlugin, Post } from 'ampless';
+export { ContentFormat } from 'ampless';
+
+interface ReadingTimeOptions {
+    /** Average words per minute. Default 200. */
+    wordsPerMinute?: number;
+    /**
+     * Template string for the label. Supports `{minutes}` and `{words}`
+     * placeholders. Default `'{minutes} min read'`.
+     */
+    labelTemplate?: string;
+    /**
+     * Where to inject the badge relative to the post body.
+     * Default `'beforeContent'`.
+     */
+    position?: 'beforeContent' | 'afterContent';
+    /**
+     * Optional namespace for this instance. Defaults to `'reading-time'`.
+     * Set a distinct value if registering the plugin more than once.
+     */
+    instanceId?: string;
+}
+/**
+ * Extract plain text from a post body. Returns an empty string for
+ * `format: 'static'` or unknown formats (safety — no badge for unreadable
+ * content).
+ */
+declare function extractPlainText(post: Post): string;
+/**
+ * Count the "reading units" in a plain-text string.
+ *
+ * - English words: whitespace-separated tokens (standard WPM baseline).
+ * - CJK characters (Han, Hiragana, Katakana): each 2 characters ≈ 1 reading
+ *   unit (roughly half the per-minute rate vs. English), so we count them and
+ *   divide by 2.
+ *
+ * For multilingual posts, both counts are summed to give a combined word
+ * estimate that feeds into the WPM calculation.
+ */
+declare function countWords(text: string): number;
+/**
+ * Coerce an unknown `wordsPerMinute` value (constructor option or stored
+ * setting) to a usable number inside the admin field's `[50, 1000]`
+ * range. Anything outside that — `0`, negative, `NaN`, `Infinity`, a
+ * non-number, or a string that can't parse — falls back to `fallback`.
+ *
+ * The admin UI's `min: 50, max: 1000` validators already gate
+ * hand-edited settings, but the constructor option is public API and
+ * a stored value can in theory be hand-edited in DynamoDB. Without
+ * this guard, `readingTimePlugin({ wordsPerMinute: 0 })` would emit
+ * `data-minutes="Infinity"` and `'Infinity min read'`.
+ */
+declare function normalizeWpm(value: unknown, fallback: number): number;
+/**
+ * Escape characters that have special meaning in HTML attribute values and
+ * text content. Applied to the rendered label string after placeholder
+ * substitution — prevents XSS when a `labelTemplate` or stored setting
+ * contains angle brackets or quotes.
+ *
+ * Only the five characters with HTML significance are replaced; no external
+ * library is needed for this narrow use case.
+ */
+declare function escapeHtml(s: string): string;
+/**
+ * Factory for the reading-time badge plugin. Returns a plugin that injects
+ * a `<p class="ampless-reading-time">` element before or after the post
+ * body via the `publicHtmlForPost` capability. The badge is omitted when the
+ * post has no readable content (e.g. `format: 'static'`, empty body).
+ *
+ * Usage in `cms.config.ts`:
+ *
+ * ```ts
+ * import readingTimePlugin from '@ampless/plugin-reading-time'
+ *
+ * export default defineConfig({
+ *   plugins: [readingTimePlugin()],
+ * })
+ * ```
+ *
+ * All options are also editable from `/admin/plugins → Reading time` without
+ * a redeploy — the constructor values below are the initial defaults.
+ */
+declare function readingTimePlugin(options?: ReadingTimeOptions): AmplessPlugin;
+
+export { type ReadingTimeOptions, countWords, readingTimePlugin as default, escapeHtml, extractPlainText, normalizeWpm };

package/dist/index.js

@@ -0,0 +1,157 @@
+// src/index.ts
+import { definePlugin } from "ampless";
+function extractTiptapText(node) {
+  if (!node || typeof node !== "object") return "";
+  const n = node;
+  if (n.type === "text" && typeof n.text === "string") {
+    return n.text;
+  }
+  if (Array.isArray(n.content)) {
+    return n.content.map((child) => extractTiptapText(child)).join(" ");
+  }
+  return "";
+}
+function extractPlainText(post) {
+  switch (post.format) {
+    case "tiptap": {
+      return extractTiptapText(post.body);
+    }
+    case "markdown": {
+      if (typeof post.body !== "string") return "";
+      return post.body.replace(/```[\s\S]*?```/g, " ").replace(/`[^`]*`/g, " ").replace(/^#{1,6}\s+/gm, "").replace(/!\[[^\]]*\]\([^)]*\)/g, " ").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/[*_~]{1,3}/g, "").replace(/<[^>]+>/g, " ");
+    }
+    case "html": {
+      if (typeof post.body !== "string") return "";
+      return post.body.replace(/<[^>]+>/g, " ");
+    }
+    case "static": {
+      return "";
+    }
+    default: {
+      return "";
+    }
+  }
+}
+function countWords(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return 0;
+  const cjkMatches = trimmed.match(/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/gu);
+  const cjkChars = cjkMatches ? cjkMatches.length : 0;
+  const withoutCjk = trimmed.replace(
+    /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/gu,
+    " "
+  );
+  const englishMatches = withoutCjk.match(/[\p{L}\p{N}][\p{L}\p{N}'-]*/gu);
+  const englishWords = englishMatches ? englishMatches.length : 0;
+  return englishWords + Math.ceil(cjkChars / 2);
+}
+function normalizeWpm(value, fallback) {
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  if (n < 50 || n > 1e3) return fallback;
+  return n;
+}
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function readingTimePlugin(options = {}) {
+  const {
+    wordsPerMinute: rawWpm = 200,
+    labelTemplate: defaultTemplate = "{minutes} min read",
+    position: defaultPosition = "beforeContent",
+    instanceId
+  } = options;
+  const defaultWpm = normalizeWpm(rawWpm, 200);
+  return definePlugin({
+    name: "reading-time",
+    packageName: "@ampless/plugin-reading-time",
+    instanceId,
+    displayName: { en: "Reading time", ja: "\u8AAD\u4E86\u6642\u9593" },
+    apiVersion: 1,
+    trust_level: "untrusted",
+    capabilities: ["publicHtmlForPost", "adminSettings"],
+    settings: {
+      public: [
+        {
+          type: "number",
+          key: "wordsPerMinute",
+          label: {
+            en: "Words per minute",
+            ja: "1 \u5206\u3042\u305F\u308A\u306E\u8A9E\u6570"
+          },
+          description: {
+            en: "Assumed reading speed. Typical adult reading speed is 200\u2013250 WPM for English, roughly 400\u2013500 characters per minute for Japanese.",
+            ja: "\u60F3\u5B9A\u8AAD\u66F8\u901F\u5EA6\u3002\u6210\u4EBA\u306E\u5E73\u5747\u306F\u82F1\u8A9E 200\u301C250 WPM\u3001\u65E5\u672C\u8A9E 400\u301C500 \u6587\u5B57/\u5206\u304C\u76EE\u5B89\u3002"
+          },
+          min: 50,
+          max: 1e3,
+          default: defaultWpm
+        },
+        {
+          type: "text",
+          key: "labelTemplate",
+          maxLength: 200,
+          label: {
+            en: "Label template",
+            ja: "\u30E9\u30D9\u30EB\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8"
+          },
+          description: {
+            en: "Template for the reading-time label. Use {minutes} for the minute count and {words} for the word count.",
+            ja: "\u30E9\u30D9\u30EB\u306E\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u3002{minutes} \u3067\u5206\u6570\u3001{words} \u3067\u8A9E\u6570\u3092\u57CB\u3081\u8FBC\u3081\u307E\u3059\u3002"
+          },
+          default: defaultTemplate
+        },
+        {
+          type: "select",
+          key: "position",
+          label: {
+            en: "Position",
+            ja: "\u8868\u793A\u4F4D\u7F6E"
+          },
+          description: {
+            en: "Where to inject the reading-time badge relative to the post content.",
+            ja: "\u30D0\u30C3\u30B8\u3092\u672C\u6587\u306E\u524D\u5F8C\u3069\u3061\u3089\u306B\u633F\u5165\u3059\u308B\u304B\u3002"
+          },
+          options: [
+            {
+              value: "beforeContent",
+              label: { en: "Before content", ja: "\u672C\u6587\u306E\u524D" }
+            },
+            {
+              value: "afterContent",
+              label: { en: "After content", ja: "\u672C\u6587\u306E\u5F8C" }
+            }
+          ],
+          default: defaultPosition
+        }
+      ]
+    },
+    publicHtmlForPost(post, ctx) {
+      const wpm = normalizeWpm(ctx.setting("wordsPerMinute"), defaultWpm);
+      const template = (ctx.setting("labelTemplate") ?? "").trim() || defaultTemplate;
+      const position = ctx.setting("position") ?? defaultPosition;
+      const plainText = extractPlainText(post);
+      const words = countWords(plainText);
+      if (words === 0) return [];
+      const minutes = Math.max(1, Math.ceil(words / wpm));
+      const labelRaw = template.replace("{minutes}", String(minutes)).replace("{words}", String(words));
+      const escapedLabel = escapeHtml(labelRaw);
+      const body = `<p class="ampless-reading-time" data-words="${words}" data-minutes="${minutes}">${escapedLabel}</p>`;
+      return [
+        {
+          type: "html",
+          id: "display",
+          body,
+          position
+        }
+      ];
+    }
+  });
+}
+export {
+  countWords,
+  readingTimePlugin as default,
+  escapeHtml,
+  extractPlainText,
+  normalizeWpm
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@ampless/plugin-reading-time",
+  "version": "0.1.0-alpha.1",
+  "description": "Reading-time badge plugin for ampless — estimates read time from post content and injects a configurable label before or after the post body",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heavymoons/ampless.git",
+    "directory": "packages/plugin-reading-time"
+  },
+  "homepage": "https://github.com/heavymoons/ampless/tree/main/packages/plugin-reading-time#readme",
+  "bugs": "https://github.com/heavymoons/ampless/issues",
+  "dependencies": {
+    "ampless": "1.0.0-alpha.28"
+  },
+  "keywords": [
+    "ampless",
+    "plugin",
+    "ampless-plugin",
+    "reading-time",
+    "read-time",
+    "badge",
+    "cms"
+  ],
+  "amplessPlugin": {
+    "apiVersion": 1,
+    "name": "reading-time",
+    "trustLevel": "untrusted",
+    "capabilities": [
+      "publicHtmlForPost",
+      "adminSettings"
+    ],
+    "displayName": {
+      "en": "Reading time",
+      "ja": "読了時間"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}