@cubud/wen 1.0.0

package/LICENSE

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

@@ -0,0 +1,53 @@
+# 🤖 Agentic & LLM Contributor Guidelines for Wen (ƿen) Editor
+
+Hello, fellow LLM or AI Assistant! If you have been asked to help extend, debug, or refactor the Wen Editor, please read this document first. It outlines the strict architectural philosophy and boundaries of this project.
+
+## 1. The Core Philosophy
+Wen is a vanilla JavaScript, dependency-light, ESM-native rich text editor built on top of TipTap and ProseMirror. 
+* **Zero Build Tools:** We do not use Node.js, Webpack, Vite, or npm. We use a simple bash script (`build.sh`) that concatenates files using `cat`.
+* **ESM Only:** All third-party libraries must be imported directly from CDNs (like `https://esm.sh/`).
+* **Joyful Minimalism:** The editor is named after the Anglo-Saxon rune ƿ (wynn), meaning "joy". Keep the UI polished, the codebase tiny, and the dependencies strictly limited.
+
+## 2. The "Dumb Router" Architecture
+Wen bridges the gap between raw Markdown and rich visual interfaces without destroying the underlying Markdown AST. **Do not create custom TipTap nodes for everything.** Instead, we use a "Dumb Router" pattern:
+1. All complex data (YAML, Components, Mermaid, Charts) is stored in the Markdown as standard fenced code blocks (e.g., ````yaml`).
+2. The core extension (`WenSmartBlocks` in `wen-core.js`) intercepts these standard code blocks based on their language tag.
+3. It routes the rendering to independent `NodeView` classes (e.g., `WenYamlView`, `WenMermaidView`).
+
+**If the user asks you to add a new block type (like a Kanban board or a Math renderer):**
+* Do NOT rewrite the TipTap schema.
+* DO create a new class that intercepts a specific code block language.
+* DO ensure the raw text remains pure and standard Markdown.
+
+## 3. The View Class Pattern
+Every custom block view MUST implement the following structure:
+* **Visual vs. Raw Toggle:** The UI must provide a way to flip between the beautiful visual rendering and the raw text/JSON/XML code.
+* **State Synchronization:** You must implement a `updateTipTapState(newContent)` function that safely updates the ProseMirror transaction without crashing the editor cursor.
+* **The `update()` Hook:** You must implement TipTap's `update(updatedNode)` method to listen for external changes (e.g., if the user edits the code via a split-pane Monaco editor) and re-render the visual state dynamically.
+
+## 4. Modal and Recursion Rules
+Wen supports deep UI recursion (e.g., a component containing markdown, which contains another component).
+* Do not attempt to render inline WYSIWYG editors inside of custom NodeViews; the DOM cannot handle the event-bubbling and horizontal space constraints.
+* Instead, use the `editor.wenEditorInstance.showRichModal()` method. This spawns a full-screen overlay containing a fresh, recursive instance of Wen Editor to handle inner content.
+* Always assign high `z-index` values (`99999`) to utility modals (like Link/Image prompts) so they don't get trapped beneath the recursive rich modals.
+
+## 5. CSS and Styling Strictness
+* **Encapsulation:** Prefix all classes with `.wen-`. Do not pollute the global CSS namespace.
+* **Box-Sizing:** Always apply `box-sizing: border-box` to custom block wrappers to prevent horizontal blowout when paddings are applied to 100% width textareas.
+* **Variables:** Use the provided CSS variables (e.g., `var(--wen-bg)`, `var(--wen-border)`) to ensure dark-mode/light-mode portability.
+
+## 6. Security: Safe by Default
+ƿen renders untrusted document content, so it is **safe by default** with a deliberate opt-out (`unsafe: true` in the editor config). Preserve this contract:
+* **Never** interpolate document data straight into `innerHTML` or into an HTML attribute. Use `escapeHtml()` from `src/wen-utils.js` for values and attributes — this is baseline correctness and applies in both modes.
+* For rich HTML you must inject (e.g. `marked` output), pass it through `sanitizeHtml()` from `src/wen-utils.js`, gated on `this.editor.wenEditorInstance?.unsafe`.
+* Third-party renderers must run in their safe mode by default (e.g. Mermaid `securityLevel: 'strict'`), loosening only when `unsafe` is set.
+* `WenEditor` propagates `unsafe` into recursive modal editors — keep that wiring intact when touching `showRichModal`.
+
+## 7. Development Workflow
+If you are instructed to create a new module (e.g., `src/wen-math.js`):
+1. Write the JS file and its accompanying `src/wen-math.css` file.
+2. Instruct the user to add the CSS file to the concatenation list in `build.sh`.
+3. Instruct the user to add the JS export to the temporary entry point in `build.sh`.
+4. Instruct the user to map the language tag to the new class in the `blockViews` configuration inside `index.html`.
+
+Stick to these patterns, avoid unnecessary abstractions, and help us keep the editor a joy to use and maintain.

package/README.md

@@ -0,0 +1,99 @@
+# ƿen (AKA wen / wynn / "joy") editor
+
+**Sponsored by [Cubud](https://cubud.com)**
+
+**ƿen** (pronounced *wen*) takes its name from the Anglo-Saxon runic alphabet. The rune **ƿ** (wynn) translates directly to "joy." Because it was historically transliterated as "w" (wen) but visually masquerades as the letter "p" (pen), it felt like the perfect namesake for a text editor: a tool designed to bring a little more joy to the act of writing.
+
+### 🤝 The Philosophy: A Shared Language
+
+ƿen was built to bridge a historical divide. 
+
+For years, developers have loved the clean, portable predictability of formats like Markdown, YAML, and XML components. Meanwhile, content editors and real humans have understandably preferred the immediate visual feedback of WYSIWYG (What You See Is What You Get) interfaces. 
+
+We didn't build ƿen to wage war on modern, heavy web frameworks. Instead, it is offered as a lightweight, unifying *alternative*. We've chosen to avoid a complex toolchain (no Node.js, no Webpack, no `npm install`) to build incredibly rich, extensible browser experiences _but_ acknowledge that we're only able to do this by leveraging robust and mature open source libraries like TipTap, Frappe, Lowlight, Mermaid and others.
+
+By taking abstract technical formats and wrapping them in friendly, interactive user interfaces, ƿen helps demystify developer tools for everyday writers. The ultimate goal is to encourage the wider adoption of these brilliant, plain-text concepts. When a content team gets comfortable editing YAML configurations and Markdown tables visually in ƿen, it becomes second nature to start using those same Markdown shortcuts to format a WhatsApp message, or structure a quick note on their phone. 
+
+It is about bringing developers and editors together into the same workflow, speaking the exact same language.
+
+### ✨ Core Features
+
+ƿen is an ESM-native, vanilla JavaScript editor built on top of TipTap and ProseMirror. It introduces a unique "Dumb Router" architecture that keeps your underlying data perfectly pure while providing a massively upgraded Writer Experience (WX).
+
+* **Zero-Build Extensibility:** No build step required. Just import the ESM modules directly from CDNs and stitch them together with a simple bash script.
+* **Visual YAML Frontmatter:** Writers can edit complex, nested page metadata through a clean, interactive form UI, which seamlessly serializes back to strict YAML.
+* **Recursive Component IDE:** Drop XML/React-style components right into the editor. ƿen renders them as visual wireframes with editable attribute pills. Need to edit the Markdown *inside* a component? Click "Edit in WYSIWYG" to spawn a recursive, infinite-depth rich modal.
+* **Smart Block Routing:** Type a code block, and ƿen instantly routes it to a custom UI.
+    * ```` ```mermaid ```` renders live, scalable state diagrams.
+    * ```` ```chart ```` turns simple CSV data into beautiful, on-brand Frappe Charts.
+    * ```` ```javascript ```` gracefully falls back to GitHub-dark syntax highlighting.
+* **Native Markdown Superpowers:** Full visual support for Markdown Tables, interactive Checklists, and dynamic GitHub-flavored Alerts (`[!WARNING]`), all perfectly translating back to standard text.
+
+### 📄 Optional Frontmatter
+ƿen natively supports YAML frontmatter, treating it as a highly structured interactive form. 
+
+By default, the editor intercepts blocks at the top of the file bracketed by `---`. It temporarily translates this into a standard ````yaml` code block so TipTap can safely route it to the visual `WenYamlView` UI without destroying the key/value pairs. When you export the document, ƿen seamlessly translates it back into strict `---` frontmatter.
+
+*(To disable this translation if you are using the editor for fragments rather than full pages, simply pass `useFrontmatter: false` in the configuration object).*
+
+### 🧩 Inline Component Support
+You can author custom HTML or React/JSX-style components directly in the Markdown stream:
+
+```xml
+<Hero banner="/img/bg.jpg" align="center">
+  # Hello World
+</Hero>
+```
+
+When useNativeComponents is enabled, ƿen uses a lightweight AST translation layer. It temporarily wraps these XML nodes in ````component` code blocks, allowing the "Dumb Router" to intercept them. They are rendered as interactive wireframes where attributes become editable text inputs.
+
+Because of this encapsulation, writers can safely edit the Markdown inside the component via a spawned modal without accidentally deleting the XML tags. On export, the wrapper is stripped away, leaving your pristine <Hero> tags exactly where they belong.
+
+## Installation & Usage
+
+No `npm install`. ƿen is published to npm as [`@cubud/wen`](https://www.npmjs.com/package/@cubud/wen) and served for free over the jsDelivr CDN. Just load the styles and import the modules:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@cubud/wen@1/dist/wen-full.min.css">
+<script type="module">
+  import {
+    WenEditor, WenYamlView, WenComponentView, WenMermaidView, WenChartView
+  } from 'https://cdn.jsdelivr.net/npm/@cubud/wen@1/dist/wen-full.min.js';
+
+  const editor = new WenEditor({
+    element: document.getElementById('my-editor'),
+    // Dependency Injection: Route the code blocks to the visual engines
+    blockViews: {
+      'yaml': WenYamlView,
+      'component': WenComponentView,
+      'mermaid': WenMermaidView,
+      'chart': WenChartView
+    },
+    initialMarkdown: '# Welcome to ƿen.'
+  });
+</script>
+```
+
+> Prefer ESM-native imports with automatic dependency resolution? `https://esm.sh/@cubud/wen@1` works too.
+
+## API
+
+`editor.exportMarkdown()`
+
+Serializes the current state of the editor back into a clean, strictly formatted Markdown string (including perfectly indented YAML data blocks and XML components).
+
+## Security
+
+ƿen turns Markdown, YAML, components and Mermaid diagrams into live HTML. By default it is **safe**: interpolated values are escaped, component previews are sanitized with [DOMPurify](https://github.com/cure53/DOMPurify), and Mermaid runs in `strict` mode (no inline HTML or click handlers).
+
+If you fully trust your content and want raw HTML and interactive diagrams rendered verbatim, opt in explicitly:
+
+```js
+const editor = new WenEditor({ /* ... */, unsafe: true });
+```
+
+ƿen is open source and dependency-light by design, so you're free to adapt this behaviour — but the default keeps an untrusted document from executing script in your page.
+
+## License
+
+MIT License. Build great things.