@b4moss/hyogen-md 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bicycle for Mind LLC., Kohki SHIKATA
+
+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.md

@@ -0,0 +1,130 @@
+# hyogen.md (`@b4moss/hyogen-md`)
+
+![masthead](https://raw.githubusercontent.com/b4m-oss/hyogen-md/develop/user-docs/hyogen-md-masthead.png)
+
+[![npm version](https://img.shields.io/npm/v/@b4moss/hyogen-md.svg)](https://www.npmjs.com/package/@b4moss/hyogen-md)
+[![license](https://img.shields.io/github/license/b4m-oss/hyogen-md)](./LICENSE)
+[![node](https://img.shields.io/node/v/@b4moss/hyogen-md.svg)](https://www.npmjs.com/package/@b4moss/hyogen-md)
+[![coverage](https://img.shields.io/badge/coverage-84%25-brightgreen)](#status)
+
+Extended Markdown template engine for TypeScript / JavaScript.
+
+Control flow and templating live in HTML comments (`@hg` … `@endhg` or `@@` … `@@`), so source files stay preview-friendly. The library outputs **Markdown only** (HTML is left to the consumer).
+
+- **Package name:** `@b4moss/hyogen-md`
+- **Product name:** hyogen.md（表現.md）
+- **License:** MIT
+- **Japanese README:** [README_ja.md](./README_ja.md)
+- **Changelog:** [user-docs/changelog.md](https://github.com/b4m-oss/hyogen-md/blob/develop/user-docs/changelog.md)
+- **Specs (Japanese, maintainers):** [dev-docs/](https://github.com/b4m-oss/hyogen-md/tree/develop/dev-docs)
+
+> **Homepage:** [https://github.com/b4m-oss/hyogen-md](https://github.com/b4m-oss/hyogen-md)
+
+This file is kept **in sync** at the repository root and at `app/README.md` (npm package root).
+
+---
+
+## Install
+
+```bash
+npm install @b4moss/hyogen-md
+```
+
+Requires **Node.js >= 20**.
+
+---
+
+## Quick start
+
+### Client / CSR (`@b4moss/hyogen-md/client`)
+
+```ts
+import { renderClient } from "@b4moss/hyogen-md/client";
+
+const result = await renderClient(
+  { path: "/src/index.md" },
+  { siteName: "Demo" },
+  {
+    loader: async (path) => {
+      // resolve path → file contents (virtual FS, fetch, etc.)
+      return await readSomewhere(path);
+    },
+  },
+);
+
+console.log(result.markdown);
+console.log(result.warnings);
+```
+
+### Server / SSR (`@b4moss/hyogen-md`)
+
+```ts
+import { renderServer, createNodeLoader } from "@b4moss/hyogen-md";
+
+const result = await renderServer(
+  { path: "./pages/index.md" },
+  { title: "Hello" },
+  {
+    loader: createNodeLoader(),
+    // serverContext: { apiKey: "…" }, // server-only; not available on renderClient
+  },
+);
+```
+
+### SSG batch (`build`)
+
+```ts
+import { build } from "@b4moss/hyogen-md";
+
+const { files, warnings } = await build({
+  input: "./src/**/*.md",
+  outDir: "./out",
+  context: { siteName: "Demo" },
+});
+```
+
+API details: [dev-docs/specs/api.md](https://github.com/b4m-oss/hyogen-md/blob/develop/dev-docs/specs/api.md).
+
+---
+
+## Repository layout
+
+| Path | Role |
+|------|------|
+| `app/` | Library published to npm (`files`: `dist`, plus README / LICENSE) |
+| `playground/` | Local Vite + Vue playground (**not** published to npm) |
+| `user-docs/` | User-facing docs (e.g. [changelog](https://github.com/b4m-oss/hyogen-md/blob/develop/user-docs/changelog.md)) |
+| `dev-docs/` | Specs and roadmap (**Japanese**, maintainers) |
+
+### Playground (local only)
+
+```bash
+cd playground
+npm install
+npm run dev
+```
+
+Uses `../app` via Vite alias. Virtual FS + `localStorage` only (no real disk I/O).
+
+---
+
+## Status
+
+This is **0.x**. APIs and output may change until `1.0.0`.  
+Published: **`@b4moss/hyogen-md@0.10.0`** (git tag `v0.10.0`).
+
+Playground UX is part of the **v0.10.0** product milestone but is **not** included in the npm tarball.
+
+The coverage badge reflects approximate **statement coverage for `app/`** (library) from Vitest (~84%). Initial release goal is ≥50%. It is not yet wired to CI / Codecov.
+
+---
+
+## Changelog
+
+See **[user-docs/changelog.md](https://github.com/b4m-oss/hyogen-md/blob/develop/user-docs/changelog.md)** (Japanese: [changelog_ja.md](https://github.com/b4m-oss/hyogen-md/blob/develop/user-docs/changelog_ja.md)).
+
+---
+
+## License
+
+[MIT](./LICENSE) © Kohki SHIKATA

package/README_ja.md

@@ -0,0 +1,130 @@
+# hyogen.md（`@b4moss/hyogen-md`）
+
+![masthead](https://raw.githubusercontent.com/b4m-oss/hyogen-md/develop/user-docs/hyogen-md-masthead.png)
+
+[![npm version](https://img.shields.io/npm/v/@b4moss/hyogen-md.svg)](https://www.npmjs.com/package/@b4moss/hyogen-md)
+[![license](https://img.shields.io/github/license/b4m-oss/hyogen-md)](./LICENSE)
+[![node](https://img.shields.io/node/v/@b4moss/hyogen-md.svg)](https://www.npmjs.com/package/@b4moss/hyogen-md)
+[![coverage](https://img.shields.io/badge/coverage-84%25-brightgreen)](#ステータス)
+
+TypeScript / JavaScript 向けの拡張 Markdown テンプレートエンジンです。
+
+制御構文は HTML コメント内（`@hg` … `@endhg` または `@@` … `@@`）に閉じるため、生ソースのプレビューを壊しにくいです。ライブラリの出力は **Markdown のみ**（HTML 化は利用側）。
+
+- **パッケージ名:** `@b4moss/hyogen-md`
+- **製品名:** hyogen.md（表現.md）
+- **ライセンス:** MIT
+- **English README:** [README.md](./README.md)
+- **Changelog:** [user-docs/changelog_ja.md](https://github.com/b4m-oss/hyogen-md/blob/develop/user-docs/changelog_ja.md)
+- **仕様（日本語・メンテナー向け）:** [dev-docs/](https://github.com/b4m-oss/hyogen-md/tree/develop/dev-docs)
+
+> **Homepage:** [https://github.com/b4m-oss/hyogen-md](https://github.com/b4m-oss/hyogen-md)
+
+本ファイルはリポジトリ根と `app/README_ja.md` で **同内容を同期**します。
+
+---
+
+## インストール
+
+```bash
+npm install @b4moss/hyogen-md
+```
+
+**Node.js >= 20** が必要です。
+
+---
+
+## クイックスタート
+
+### クライアント / CSR（`@b4moss/hyogen-md/client`）
+
+```ts
+import { renderClient } from "@b4moss/hyogen-md/client";
+
+const result = await renderClient(
+  { path: "/src/index.md" },
+  { siteName: "Demo" },
+  {
+    loader: async (path) => {
+      // path → ファイル内容（仮想 FS・fetch など）
+      return await readSomewhere(path);
+    },
+  },
+);
+
+console.log(result.markdown);
+console.log(result.warnings);
+```
+
+### サーバ / SSR（`@b4moss/hyogen-md`）
+
+```ts
+import { renderServer, createNodeLoader } from "@b4moss/hyogen-md";
+
+const result = await renderServer(
+  { path: "./pages/index.md" },
+  { title: "Hello" },
+  {
+    loader: createNodeLoader(),
+    // serverContext: { apiKey: "…" }, // サーバ専用。renderClient では不可
+  },
+);
+```
+
+### SSG 一括（`build`）
+
+```ts
+import { build } from "@b4moss/hyogen-md";
+
+const { files, warnings } = await build({
+  input: "./src/**/*.md",
+  outDir: "./out",
+  context: { siteName: "Demo" },
+});
+```
+
+API の詳細: [dev-docs/specs/api.md](https://github.com/b4m-oss/hyogen-md/blob/develop/dev-docs/specs/api.md)。
+
+---
+
+## リポジトリ構成
+
+| パス | 役割 |
+|------|------|
+| `app/` | npm 公開するライブラリ（`dist` + README / LICENSE） |
+| `playground/` | ローカル向け Vite + Vue プレイグラウンド（**npm 非同梱**） |
+| `user-docs/` | 利用者向けドキュメント（例: [changelog](https://github.com/b4m-oss/hyogen-md/blob/develop/user-docs/changelog_ja.md)） |
+| `dev-docs/` | 仕様・ロードマップ（**日本語**・メンテナー向け） |
+
+### プレイグラウンド（ローカルのみ）
+
+```bash
+cd playground
+npm install
+npm run dev
+```
+
+Vite alias で `../app` を参照します。仮想 FS + `localStorage` のみ（実ディスクは使いません）。
+
+---
+
+## ステータス
+
+**0.x** です。`1.0.0` まで API・出力は変わりえます。  
+公開済み: **`@b4moss/hyogen-md@0.10.0`**（git tag `v0.10.0`）。
+
+Playground UX は **v0.10.0** マイルストーンに含まれますが、**npm の tarball には入りません**。
+
+coverage バッジはライブラリ（`app/`）の Vitest **statement カバレッジ概算（約 84%）**です。初期リリース目標は 50% 以上。CI / Codecov 連携はまだありません。
+
+---
+
+## Changelog
+
+**[user-docs/changelog_ja.md](https://github.com/b4m-oss/hyogen-md/blob/develop/user-docs/changelog_ja.md)** を参照（English: [changelog.md](https://github.com/b4m-oss/hyogen-md/blob/develop/user-docs/changelog.md)）。
+
+---
+
+## ライセンス
+
+[MIT](./LICENSE) © Kohki SHIKATA

package/dist/client.d.ts

@@ -0,0 +1,46 @@
+export declare function renderClient(
+  input: string | { path: string },
+  context?: HyogenContext,
+  options?: RenderOptions & { serverContext?: HyogenContext },
+): Promise<RenderResult>;
+
+export declare function createHyogenError(options: {
+  code: string;
+  message?: string;
+  path?: string;
+  details?: Record<string, unknown>;
+}): HyogenError;
+
+export declare function formatMessage(
+  code: string,
+  details?: Record<string, unknown>,
+): string;
+
+export type HyogenContext = Record<string, unknown>;
+
+export type HyogenDiagnostic = {
+  code: string;
+  message: string;
+  path?: string;
+  details?: Record<string, unknown>;
+};
+
+export type HyogenWarning = HyogenDiagnostic;
+export type HyogenError = Error & HyogenDiagnostic;
+export type Loader = (path: string) => Promise<string>;
+
+export type RenderOptions = {
+  preserveFrontMatter?: boolean;
+  preserveHgComments?: boolean;
+  loader?: Loader;
+  root?: string;
+  path?: string;
+  constrainToRoot?: boolean;
+};
+
+export type RenderResult = {
+  markdown: string;
+  warnings: HyogenWarning[];
+};
+
+export {};