flowink 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlowInk 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/NOTICE.md

@@ -0,0 +1,17 @@
+# Third-party notices
+
+FlowInk's own source is licensed under MIT.
+
+The flowchart grammar, portions of parsing/semantic processing, and upstream
+compatibility fixtures derive from Mermaid 12.0.0 (MIT), tag `mermaid@12.0.0`,
+commit `98a0945418c76238f15df2afaddbba4272656c3b`.
+Source: https://github.com/mermaid-js/mermaid/tree/mermaid%4012.0.0
+The upstream license and grammar provenance are included in `vendor/mermaid`.
+The parser is generated at build time by Jison (MIT).
+
+Runtime dependencies retain their own licenses; they are installed separately
+and not relicensed by FlowInk. In particular, elkjs is distributed under
+`EPL-2.0 OR GPL-3.0-or-later`; its license is included in the installed elkjs
+package. See https://github.com/kieler/elkjs/blob/master/LICENSE.md.
+
+Graph::Easy is a visual reference. FlowInk contains no Graph::Easy code.

package/README.md

@@ -0,0 +1,301 @@
+<div align="center">
+
+# FlowInk
+
+**Mermaid flowcharts, rendered as text.**
+
+ASCII and Unicode diagrams for Node.js and the browser.
+
+[![npm version](https://img.shields.io/npm/v/flowink)](https://www.npmjs.com/package/flowink)
+[![JavaScript ESM](https://img.shields.io/badge/JavaScript-ESM-f7df1e?logo=javascript&logoColor=111111)](#quick-start)
+[![Mermaid 12.0.0](https://img.shields.io/badge/Mermaid-12.0.0-ff3670)](#compatibility)
+[![Node.js 22.12+](https://img.shields.io/badge/Node.js-%E2%89%A522.12-339933?logo=nodedotjs&logoColor=white)](#development)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
+
+[Quick start](#quick-start) · [Examples](#examples) · [API](#api) · [Compatibility](#compatibility) · [Development](#development)
+
+</div>
+
+<!-- example:hero:start -->
+```text
++---------+  +------------+
+| Mermaid |->| Plain text |
++---------+  +------------+
+```
+<!-- example:hero:end -->
+
+## Why FlowInk?
+
+- **Keep your Mermaid source.** Uses the official flowchart grammar pinned to Mermaid 12.0.0.
+- **Choose your alphabet.** ASCII by default, Unicode when you want box-drawing characters.
+- **Keep the graph intact.** Branches, cycles, parallel edges, self-loops, and nested subgraphs.
+- **Keep the details.** Chinese text, multiline labels, and plain-text Markdown/HTML content; styles and interactions stay in the parsed data.
+- **Use JavaScript.** ESM API, JSDoc-derived TypeScript declarations, and no runtime DOM or external executable requirement.
+
+## Quick start
+
+Requires **Node.js 22.12+**. Install from npm:
+
+```sh
+npm install flowink
+```
+
+Create `demo.mjs` in your project:
+
+```js
+import { parse, render } from 'flowink';
+
+const source = `flowchart LR
+  A[Mermaid] --> B[Plain text]
+`;
+
+console.log(await render(source));
+console.log(await render(source, { charset: 'unicode' }));
+
+const graph = parse(source);
+console.log(graph.nodes, graph.edges);
+```
+
+```sh
+node demo.mjs
+```
+
+Browser applications can import `flowink` through their usual bundler.
+
+## Examples
+
+Each output below is generated by `render()` from the accompanying source. The inputs are also available in [`examples/`](examples).
+
+### 1. A decision with two outcomes
+
+<!-- example:decision:start -->
+**Mermaid source**
+
+```text
+flowchart TB
+  A[Start] --> B{Ready?}
+  B -->|yes| C[Ship]
+  B -->|no| D[Wait]
+```
+
+**Unicode output** · `render(source, { charset: 'unicode' })`
+
+```text
+ ┌────────┐
+ │ Start  │
+ └────────┘
+   ┌─┘
+   ▼
+ ╱────────╲
+ │        │
+ ◁ Ready? ▷
+ │        │
+ ╲────────╱
+    ┌┘ │
+    │  └─────┐
+    │    no  │
+yes │        │
+    │        │
+    │        │
+    ▼        ▼
+┌───────┐┌───────┐
+│ Ship  ││ Wait  │
+└───────┘└───────┘
+```
+<!-- example:decision:end -->
+
+### 2. Chinese and multiline labels
+
+Drawing characters and label text are independent: ASCII mode also preserves Chinese and other Unicode labels. Use a monospace font with suitable CJK and emoji support.
+
+<!-- example:chinese:start -->
+**Mermaid source**
+
+```text
+flowchart LR
+  A["開始"] -->|確認| B["完成<br/>下一步"]
+```
+
+**Unicode output** · `render(source, { charset: 'unicode' })`
+
+```text
+          確認
+┌──────┐         ┌────────┐
+│ 開始 │────────▶│  完成  │
+│      │         │ 下一步 │
+└──────┘         └────────┘
+```
+<!-- example:chinese:end -->
+
+<details>
+<summary><strong>3. A cycle — follow the return edge</strong></summary>
+
+<!-- example:cycle:start -->
+**Mermaid source**
+
+```text
+flowchart TB
+  A[Plan] --> B[Build] --> C[Review] --> A
+```
+
+**ASCII output** · `render(source, { charset: 'ascii' })`
+
+```text
+ +-------+
+ | Plan  |
+ +-------+
+  ++ ^
+  |  +----+
+  v       |
++-------+ |
+| Build | |
++-------+ |
+   ++     |
+   |      |
+   v +----+
+ +--------+
+ | Review |
+ +--------+
+```
+<!-- example:cycle:end -->
+
+</details>
+
+<details>
+<summary><strong>4. A subgraph with an outgoing connection</strong></summary>
+
+<!-- example:subgraph:start -->
+**Mermaid source**
+
+```text
+flowchart TB
+  subgraph Build
+    A[Parse] --> B[Layout]
+  end
+  B --> C[Text]
+```
+
+**ASCII output** · `render(source, { charset: 'ascii' })`
+
+```text
++------------+
+|   Build    |
+| +--------+ |
+| | Parse  | |
+| +--------+ |
+|   +-+      |
+|   v        |
+| +--------+ |
+| | Layout | |
+| +--------+ |
+|     |      |
++-----|------+
+      |
+      |
+      v
+   +------+
+   | Text |
+   +------+
+```
+<!-- example:subgraph:end -->
+
+</details>
+
+## API
+
+### `render(source, options?) → Promise<string>`
+
+```js
+const ascii = await render(source);
+const unicode = await render(source, { charset: 'unicode' });
+```
+
+| Option | Values | Default |
+| --- | --- | --- |
+| `charset` | `'ascii'`, `'unicode'` | `'ascii'` |
+
+Output has no trailing spaces or trailing newline. There is no fixed total width, and labels are not truncated. Dense diagrams may expand to preserve wire spacing and readable label placement.
+
+### `parse(source) → FlowGraph`
+
+Returns an independent, serializable graph, retaining the exact original input.
+
+| Field | Contents |
+| --- | --- |
+| `source` | Original Mermaid source |
+| `direction` | Normalized flow direction |
+| `nodes` | IDs, labels, label types, shapes, parents, styles, classes, metadata |
+| `edges` | IDs, endpoints, labels, arrows, stroke, length, styles, classes, metadata |
+| `subgraphs` | IDs, titles, membership, hierarchy, local directions, metadata |
+| `classes` | Named style definitions |
+| `metadata` | Frontmatter, directives, accessibility information, and other non-drawing data |
+
+### Errors
+
+```js
+import { FlowInkError, render } from 'flowink';
+
+try {
+  console.log(await render(source));
+} catch (error) {
+  if (error instanceof FlowInkError) {
+    console.error(error.code, error.message);
+    if (error.line !== undefined) {
+      console.error(`Line ${error.line}, column ${error.column}`);
+    }
+  } else {
+    throw error;
+  }
+}
+```
+
+Located syntax errors use one-based lines and columns in the original source. Layout failures are reported explicitly; a successful render must not silently omit an edge.
+
+## Compatibility
+
+**The baseline is Mermaid 12.0.0**, tag `mermaid@12.0.0`, commit [`98a0945`](https://github.com/mermaid-js/mermaid/tree/98a0945418c76238f15df2afaddbba4272656c3b). The official Jison grammar is vendored unchanged and generated into JavaScript during the build. See [grammar provenance](vendor/mermaid/README.md).
+
+```text
+Mermaid source → parser + graph model → ELK layout → character grid → text
+```
+
+| Feature | Text representation |
+| --- | --- |
+| Flowchart/graph syntax, chained links, multi-node links, edge IDs | Parsed using the pinned upstream grammar |
+| Branches, cycles, parallel edges, self-loops | Orthogonal routes with separate endpoints and collision checks |
+| Nested subgraphs and cross-boundary edges | Containers with Mermaid's direction inheritance behavior |
+| Common node shapes | Text approximations |
+| Other shapes, images, icons | Shape annotations or text placeholders |
+| HTML and Markdown labels | Plain text, preserving line breaks and entities |
+| Colors, CSS, animation, links, callbacks | Retained as data; callbacks are not executed and images are not fetched |
+| Invisible edges | Influence layout without visible strokes |
+
+FlowInk uses its own text layout rather than Mermaid SVG coordinates. Nonjoining crossings use `#` in ASCII and `╳` in Unicode, distinct from corners and junctions. Alignment follows character display widths; fonts and terminals can differ in their Unicode width conventions.
+
+Compatibility covers this version's **flowcharts**, not other Mermaid diagram types or future releases. The first version supplies the package API; a CLI and editor UI are outside its current scope.
+
+## Development
+
+```sh
+git clone https://github.com/william1010121/flowink.git
+cd flowink
+npm ci
+npm run build
+npm test
+npm run test:types
+npm run test:package
+```
+
+### Verification
+
+The suite covers **435 upstream fixtures**, including complete static inputs and bounded arrow, length, keyword, and character matrices. It also checks graph geometry, labels, Unicode widths, error locations, and repeated/concurrent calls.
+
+- **Parser comparison:** upstream cases use Mermaid's raw parser and FlowDB; preprocessing cases use Mermaid's public API. [Fixture provenance and exclusions](test/fixtures/upstream/README.md).
+- **Package installation:** `test:package` checks archive contents and installs the tarball in a temporary directory outside the project.
+- **Browser execution:** `npm run test:browser:build` generates `.cache/browser-smoke/index.html`. Serve that directory over HTTP and open the page to compare five diagrams in both charsets against Node.js output. Results are available in `window.__flowinkSmoke`.
+
+Fixtures are checked in, so tests do not download upstream source on each run. Mermaid itself is a development-only oracle dependency. Rendering is asynchronous but still uses CPU; applications can run large layouts in their own worker.
+
+## License
+
+FlowInk's own code is [MIT](LICENSE). Mermaid-derived files retain their MIT attribution. Runtime dependencies retain their own licenses, including elkjs's `EPL-2.0 OR GPL-3.0-or-later`. See [third-party notices](NOTICE.md).

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+/** An input or layout error. Locations refer to the original Mermaid source. */
+export class FlowInkError extends Error {
+    /** @param {string} message @param {{code?:string,line?:number,column?:number,cause?:unknown}} [options] */
+    constructor(message: string, options?: {
+        code?: string;
+        line?: number;
+        column?: number;
+        cause?: unknown;
+    });
+    code: string;
+    line: number;
+    column: number;
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/** @typedef {import('./types.js').FlowGraph} FlowGraph */
+/** @typedef {import('./types.js').RenderOptions} RenderOptions */
+/**
+ * Render a Mermaid 12.0.0 flowchart as a plain text diagram.
+ * @param {string} source Mermaid flowchart source.
+ * @param {RenderOptions} [options]
+ * @returns {Promise<string>}
+ */
+export function render(source: string, options?: RenderOptions): Promise<string>;
+export type FlowGraph = import("./types.js").FlowGraph;
+export type RenderOptions = import("./types.js").RenderOptions;
+import { parse } from './parse.js';
+import { FlowInkError } from './errors.js';
+export { parse, FlowInkError };