zig-pug 0.2.0 → 0.3.1

package/README.md

@@ -1,19 +1,23 @@
 # zig-pug
 
-High-performance Pug template engine powered by Zig and mujs - Native N-API addon with ES5.1 JavaScript support.
+High-performance Pug template engine powered by Zig and mujs.
 
 [![npm version](https://img.shields.io/npm/v/zig-pug.svg)](https://www.npmjs.com/package/zig-pug)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![license](https://img.shields.io/npm/l/zig-pug.svg)](https://github.com/carlos-sweb/zig-pug/blob/main/LICENSE)
 
 ## Features
 
-- **Blazing Fast**: Written in Zig with native N-API bindings
-- **Lightweight**: ~500KB total (includes mujs JavaScript engine)
-- **Modern**: Zig 0.15 best practices with StaticStringMap O(1) lookups
-- **Secure**: Built-in XSS protection with automatic HTML escaping
-- **Simple API**: Easy-to-use JavaScript interface
-- **Cross-Platform**: Precompiled binaries for Linux, macOS, and Windows
-- **Node.js Compatible**: Works with Node.js 14+ and Bun.js
+- ✅ **Pug syntax** - Tags, attributes, classes, IDs
+- ✅ **JavaScript expressions** - ES5.1 interpolation powered by mujs
+- ✅ **Full UTF-8 support** - Emoji 🎉, accents (á é ñ ü), all Unicode
+- ✅ **Documentation comments** - `//!` for file metadata (ignored by parser)
+- ✅ **Conditionals** - if/else/unless
+- ✅ **Mixins** - Reusable components
+- ✅ **Dual package** - CommonJS (`require`) and ES Modules (`import`)
+- ✅ **Bun.js compatible** - 2-5x faster than Node.js
+- ⚡ **Native performance** - Written in Zig, compiled to native code
+- 🔋 **Zero dependencies** - Only Zig and embedded mujs
+- 🌍 **i18n ready** - Spanish, Portuguese, French, German, and more
 
 ## Installation
 
@@ -21,326 +25,389 @@ High-performance Pug template engine powered by Zig and mujs - Native N-API addo
 npm install zig-pug
 ```
 
-Precompiled binaries are automatically downloaded for your platform. If no binary is available, it will build from source (requires Zig 0.15+).
+**Requirements:**
+- Node.js >= 14.0.0
+- C/C++ compiler (GCC, Clang, or MSVC)
+- Python (for node-gyp)
+
+The addon will compile automatically during installation.
 
 ## Quick Start
 
-```javascript
-const { compile } = require('zig-pug');
+### Simple API
 
-// Simple template
-const html = compile('h1 Hello, World!');
-console.log(html); // <h1>Hello, World!</h1>
+**CommonJS (Node.js):**
+```javascript
+const zigpug = require('zig-pug');
 
-// With variables
-const html2 = compile('h1 Hello, #{name}!', { name: 'Alice' });
-console.log(html2); // <h1>Hello, Alice!</h1>
+const html = zigpug.compile('p Hello #{name}!', { name: 'World' });
+console.log(html);
+// <p>Hello World!</p>
 ```
 
-## API Reference
+**ES Modules (Node.js, Bun):**
+```javascript
+import { compile } from 'zig-pug';
 
-### compile(template, variables)
+const html = compile('p Hello #{name}!', { name: 'World' });
+console.log(html);
+// <p>Hello World!</p>
+```
 
-Compile a Pug template string to HTML.
+### Object-Oriented API
 
+**CommonJS (Node.js):**
 ```javascript
-const { compile } = require('zig-pug');
+const { PugCompiler } = require('zig-pug');
+
+const compiler = new PugCompiler();
+compiler
+    .set('title', 'My Page')
+    .set('version', 1.5)
+    .setBool('isDev', false);
 
-const html = compile('p Hello, #{name}!', { name: 'Bob' });
-console.log(html); // <p>Hello, Bob!</p>
+const html = compiler.compile('h1 #{title}');
+console.log(html);
+// <h1>My Page</h1>
 ```
 
-**Parameters:**
-- `template` (string): Pug template string
-- `variables` (object, optional): Variables to interpolate
+**ES Modules (Node.js, Bun):**
+```javascript
+import { PugCompiler } from 'zig-pug';
 
-**Returns:** Compiled HTML string
+const compiler = new PugCompiler();
+compiler
+    .set('title', 'My Page')
+    .set('version', 1.5)
+    .setBool('isDev', false);
 
-### compileFile(filename, variables)
+const html = compiler.compile('h1 #{title}');
+console.log(html);
+// <h1>My Page</h1>
+```
 
-Compile a Pug template file to HTML.
+### Express Integration
 
 ```javascript
-const { compileFile } = require('zig-pug');
+const express = require('express');
+const zigpug = require('zig-pug');
+const fs = require('fs');
+
+const app = express();
+
+// Load template once at startup
+const homeTemplate = fs.readFileSync('./views/home.pug', 'utf-8');
 
-const html = compileFile('./views/index.pug', {
-  title: 'My Page',
-  user: 'Alice'
+app.get('/', (req, res) => {
+    const html = zigpug.compile(homeTemplate, {
+        title: 'Home',
+        user: req.user
+    });
+    res.send(html);
 });
+
+app.listen(3000);
 ```
 
-**Parameters:**
-- `filename` (string): Path to Pug template file
-- `variables` (object, optional): Variables to interpolate
+## Bun.js Support
 
-**Returns:** Compiled HTML string
+zig-pug works seamlessly with Bun, the ultra-fast JavaScript runtime:
 
-### ZigPugCompiler Class
+```bash
+bun install zig-pug
+bun run app.js
+```
 
-For multiple compilations, use the `ZigPugCompiler` class to reuse the context:
+**Performance:** Bun is 2-5x faster than Node.js for template compilation.
 
-```javascript
-const { ZigPugCompiler } = require('zig-pug');
+See [examples/bun/](https://github.com/carlos-sweb/zig-pug/tree/main/examples/bun) for complete examples.
 
-const compiler = new ZigPugCompiler();
+## Pug Syntax
 
-// Set variables
-compiler.setString('name', 'Alice');
-compiler.setNumber('age', 30);
-compiler.setBool('premium', true);
+### Tags and Attributes
 
-// Or set multiple at once
-compiler.setVariables({
-  name: 'Bob',
-  age: 25,
-  premium: false
-});
+```pug
+div.container
+  h1#title Hello World
+  p.text(data-id="123") Content
+  a(href="/" target="_blank") Link
+```
+
+### JavaScript Interpolation
 
-// Compile templates
-const html1 = compiler.compile('p Hello, #{name}!');
-const html2 = compiler.compile('p Age: #{age}');
+```pug
+p Hello #{name}!
+p Age: #{age + 1}
+p Email: #{email.toLowerCase()}
+p Status: #{age >= 18 ? 'Adult' : 'Minor'}
+p Max: #{Math.max(10, 20)}
 ```
 
-**Methods:**
-- `setString(key, value)` - Set a string variable
-- `setNumber(key, value)` - Set a number variable
-- `setBool(key, value)` - Set a boolean variable
-- `set(key, value)` - Auto-detect type and set variable
-- `setVariables(obj)` - Set multiple variables from object
-- `compile(template)` - Compile template with current variables
-- `render(template, variables)` - Set variables and compile in one call
+**Supported JavaScript (ES5.1):**
+- String methods: `toLowerCase()`, `toUpperCase()`, `split()`, etc.
+- Math: `Math.max()`, `Math.min()`, `Math.random()`, etc.
+- Operators: `+`, `-`, `*`, `/`, `%`, `&&`, `||`, `?:`
+- Object/Array access: `obj.prop`, `arr[0]`, `arr.length`
 
-### version()
+### Conditionals
 
-Get the zig-pug version.
+```pug
+if isLoggedIn
+  p Welcome back!
+else
+  p Please log in
 
-```javascript
-const { version } = require('zig-pug');
-console.log(version()); // 0.2.0
+unless isAdmin
+  p Access denied
 ```
 
-## Pug Syntax Support
-
-### Tags
+### Mixins
 
 ```pug
-div
-  p Hello, World!
-  span.class-name#id-name Text content
-```
+mixin button(text)
+  button.btn= text
 
-```html
-<div>
-  <p>Hello, World!</p>
-  <span class="class-name" id="id-name">Text content</span>
-</div>
++button('Click me')
++button('Submit')
 ```
 
-### Attributes
+### UTF-8 & Unicode Support
+
+Full support for international characters, emoji, and symbols:
 
 ```pug
-a(href="https://example.com" target="_blank") Link
-input(type="text" name="username" required)
+//! File: index.pug
+//! Author: Carlos
+doctype html
+html(lang="es")
+  head
+    title #{titulo}
+  body
+    h1 ¡Bienvenido! 🎉
+
+    section.español
+      p.información Información sobre José y María
+      p#descripción Este párrafo tiene ID con acento
+
+    section.português
+      h2 Programação em português
+      p Características: ã, õ, ç
+
+    section.français
+      h2 Génération française
+      p Avec é, è, ê, ç
+
+    footer
+      p © 2025 - Creado con zig-pug 🚀
 ```
 
-```html
-<a href="https://example.com" target="_blank">Link</a>
-<input type="text" name="username" required />
-```
+**Supported everywhere:**
+- ✅ Text content: `p José, María, Ángel`
+- ✅ Class names: `.información .português`
+- ✅ ID attributes: `#descripción #größe`
+- ✅ Comments: `// útil para depuración`
+- ✅ Emoji: `h1 Hello 🎉 🚀 ✨`
+- ✅ Symbols: `p © ™ € £ ¥`
+
+### Documentation Comments
 
-### Interpolation
+Use `//!` for file metadata that won't appear in output:
 
 ```pug
-p Hello, #{name}!
-p Age: #{age}
-p Premium: #{premium}
+//! Template: homepage.pug
+//! Author: John Doe
+//! Version: 1.0
+//! Description: Main landing page
+doctype html
+html
+  body
+    // Regular comment (appears in --pretty mode)
+    //- Code comment (never appears)
 ```
 
-With variables: `{ name: 'Alice', age: 30, premium: true }`
+| Syntax | Name | In HTML? | Use Case |
+|--------|------|----------|----------|
+| `//!` | Documentation | ❌ Never | File metadata, notes |
+| `//` | Buffered | ✅ Dev mode | Development debugging |
+| `//-` | Unbuffered | ❌ Never | Code comments |
 
-```html
-<p>Hello, Alice!</p>
-<p>Age: 30</p>
-<p>Premium: true</p>
-```
+## API Reference
+
+### `compile(template, data)`
 
-### HTML Escaping
+Compile a template with data.
+
+**Parameters:**
+- `template` (string) - Pug template source
+- `data` (object) - Variables to interpolate
 
-Automatic XSS protection:
+**Returns:** (string) Compiled HTML
 
 ```javascript
-const html = compile('p #{userInput}', {
-  userInput: '<script>alert("XSS")</script>'
-});
-// <p>&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;</p>
+const html = zigpug.compile(
+    'p Hello #{name}!',
+    { name: 'Alice' }
+);
 ```
 
-### Void Elements
+### `PugCompiler`
 
-Self-closing tags are handled automatically:
+Reusable compiler with state.
 
-```pug
-br
-hr
-img(src="logo.png")
-input(type="text")
-```
+```javascript
+const { PugCompiler } = require('zig-pug');
+
+const compiler = new PugCompiler();
+compiler.set('key', 'value');      // String/Number
+compiler.setBool('flag', true);    // Boolean
 
-```html
-<br />
-<hr />
-<img src="logo.png" />
-<input type="text" />
+const html = compiler.compile(template);
 ```
 
-## Usage Examples
+**Methods:**
+- `set(key, value)` - Set string or number variable
+- `setBool(key, value)` - Set boolean variable
+- `compile(template)` - Compile template with current variables
 
-### Express Integration
+### `version()`
+
+Get zig-pug version.
 
 ```javascript
-const express = require('express');
-const { compileFile } = require('zig-pug');
-const app = express();
+console.log(zigpug.version()); // "0.2.0"
+```
 
-app.get('/', (req, res) => {
-  const html = compileFile('./views/index.pug', {
-    title: 'Home Page',
-    user: req.user
-  });
-  res.send(html);
-});
+## Platform Support
 
-app.listen(3000);
-```
+### Supported Platforms
 
-### Koa Integration
+- ✅ **Linux** (x64, ARM64)
+- ✅ **macOS** (x64, Apple Silicon)
+- ✅ **Windows** (x64)
+- ✅ **Bun.js** (all platforms)
 
-```javascript
-const Koa = require('koa');
-const { compileFile } = require('zig-pug');
-const app = new Koa();
-
-app.use(async ctx => {
-  const html = compileFile('./views/index.pug', {
-    title: 'Home Page',
-    path: ctx.path
-  });
-  ctx.body = html;
-});
+### Termux/Android
 
-app.listen(3000);
-```
+The addon compiles on Termux but cannot be loaded due to Android namespace restrictions. Use the standalone CLI binary instead:
 
-### Bun.js Integration
+```bash
+# Install Zig
+pkg install zig
 
-```javascript
-import { compile } from 'zig-pug';
+# Clone and build
+git clone https://github.com/yourusername/zig-pug
+cd zig-pug
+zig build
 
-Bun.serve({
-  port: 3000,
-  fetch(req) {
-    const html = compile('h1 Hello from Bun!');
-    return new Response(html, {
-      headers: { 'Content-Type': 'text/html' }
-    });
-  }
-});
+# Use CLI
+./zig-out/bin/zig-pug template.pug
 ```
 
+See [docs/TERMUX.md](https://github.com/yourusername/zig-pug/blob/main/docs/TERMUX.md) for details.
+
 ## Performance
 
-zig-pug is designed for performance:
+### Benchmark
 
-- **O(1) lookups**: StaticStringMap for void element checks
-- **Optimized I/O**: Writer pattern reduces allocations
-- **Native code**: Zig compiles to machine code
-- **Lightweight**: No heavy dependencies
-- **Fast startup**: mujs has minimal overhead
+```javascript
+const iterations = 10000;
+const start = Date.now();
 
-## Security
+for (let i = 0; i < iterations; i++) {
+    zigpug.compile(template, data);
+}
 
-- **Automatic HTML escaping**: All interpolated values are escaped by default
-- **XSS prevention**: Built-in protection against cross-site scripting
-- **Safe parsing**: Zig's memory safety prevents buffer overflows
-- **No eval()**: Templates are compiled, not evaluated
+const elapsed = Date.now() - start;
+console.log(`${iterations} in ${elapsed}ms`);
+// ~100-250k ops/sec depending on runtime
+```
 
-## Building from Source
+### Tips
 
-If precompiled binaries are not available for your platform:
+1. **Reuse PugCompiler** - Faster than creating new context each time
+2. **Pre-load templates** - Read files once at startup
+3. **Use Bun.js** - 2-5x faster than Node.js
 
-### Prerequisites
+## Examples
 
-- Node.js 14+
-- Zig 0.15+
-- Python 3
-- C compiler (gcc/clang)
+See the [examples](https://github.com/yourusername/zig-pug/tree/main/examples) directory:
 
-### Build Steps
+- **Node.js**: `examples/nodejs/`
+- **Bun.js**: `examples/bun/`
+- **Express**: `examples/nodejs/05-express-integration.js`
 
-From the repository root:
+## Documentation
 
-```bash
-# Build the addon (builds library + addon + copies library to build dir)
-zig build node
+- **[Getting Started](https://github.com/yourusername/zig-pug/blob/main/docs/GETTING-STARTED.md)**
+- **[Node.js Integration](https://github.com/yourusername/zig-pug/blob/main/docs/NODEJS-INTEGRATION.md)**
+- **[Pug Syntax Reference](https://github.com/yourusername/zig-pug/blob/main/docs/PUG-SYNTAX.md)**
+- **[API Reference](https://github.com/yourusername/zig-pug/blob/main/docs/API-REFERENCE.md)**
 
-# Or from nodejs directory
-cd nodejs && npm run build
-```
+## Troubleshooting
+
+### Installation fails
+
+**Error:** `node-gyp rebuild` fails
 
-### Running Examples and Tests
+**Solution:** Install build tools:
 
 ```bash
-# From nodejs directory
-npm test        # Run test suite
-npm run example # Run example
+# Ubuntu/Debian
+sudo apt-get install build-essential python3
 
-# Or directly with node (after building)
-node test/test.js
-node example.js
+# macOS
+xcode-select --install
+
+# Windows
+npm install --global windows-build-tools
 ```
 
-**Note:** The build process automatically copies `libzigpug.so` to the `build/Release/` directory, so you don't need to set `LD_LIBRARY_PATH` manually.
+### Module not found
 
-See [BUILD_GUIDE.md](BUILD_GUIDE.md) for detailed build instructions.
+**Error:** `Cannot find module 'zig-pug'`
 
-## Architecture
+**Solution:** Rebuild the addon:
 
+```bash
+cd node_modules/zig-pug
+npm run build
 ```
-┌─────────────────────────────────────────────┐
-│  Node.js Application                        │
-│  (your code)                                │
-└────────────┬────────────────────────────────┘
-             │ require('zig-pug')
-             ↓
-┌─────────────────────────────────────────────┐
-│  N-API Addon (binding.c)                    │
-│  - JavaScript API wrapper                   │
-└────────────┬────────────────────────────────┘
-             │ FFI calls
-             ↓
-┌─────────────────────────────────────────────┐
-│  libzigpug.so (Zig + mujs)                  │
-│  - Tokenizer → Parser → Compiler → HTML    │
-└─────────────────────────────────────────────┘
-```
+
+### Compilation errors
+
+If you encounter compilation errors, please [open an issue](https://github.com/yourusername/zig-pug/issues) with:
+- Your OS and version
+- Node.js version (`node --version`)
+- Complete error output
 
 ## Contributing
 
-Contributions are welcome! Please see the main repository for contributing guidelines.
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `npm test`
+5. Submit a pull request
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
+MIT License - see [LICENSE](https://github.com/yourusername/zig-pug/blob/main/LICENSE) for details.
+
+## Credits
+
+- **[Pug](https://pugjs.org/)** - Original inspiration
+- **[Zig](https://ziglang.org/)** - Programming language
+- **[mujs](https://mujs.com/)** - Embedded JavaScript engine
+- **[Artifex Software](https://artifex.com/)** - Creators of mujs
 
 ## Links
 
-- [GitHub Repository](https://github.com/carlos-sweb/zig-pug)
-- [npm Package](https://www.npmjs.com/package/zig-pug)
-- [Issue Tracker](https://github.com/carlos-sweb/zig-pug/issues)
-- [Build Guide](BUILD_GUIDE.md)
+- **GitHub**: https://github.com/yourusername/zig-pug
+- **npm**: https://www.npmjs.com/package/zig-pug
+- **Issues**: https://github.com/yourusername/zig-pug/issues
+- **Documentation**: https://github.com/yourusername/zig-pug#readme
 
-## Credits
+---
 
-- Built by [carlos-sweb](https://github.com/carlos-sweb)
-- Powered by [Zig](https://ziglang.org/) and [mujs](https://mujs.com/)
-- Inspired by the original [Pug](https://pugjs.org/) template engine
+Made with ❤️ using Zig 0.15.2 and mujs

package/binding.gyp

@@ -3,25 +3,22 @@
     {
       "target_name": "zigpug",
       "sources": [
-        "binding.c"
+        "binding.c",
+        "vendor/mujs/one.c"
       ],
       "include_dirs": [
         "include",
-        "../vendor/mujs"
+        "vendor/mujs"
       ],
       "libraries": [
-        "-L<(module_root_dir)",
-        "-lzigpug",
         "-lm"
       ],
       "cflags": [
-        "-std=c99"
+        "-std=c99",
+        "-DHAVE_STRLCPY=0"
       ],
       "defines": [
         "NAPI_VERSION=8"
-      ],
-      "ldflags": [
-        "-Wl,-rpath,'$$ORIGIN'"
       ]
     }
   ]

package/index.js

@@ -3,32 +3,12 @@
  * Powered by Zig and mujs
  */
 
-const binary = require('@mapbox/node-pre-gyp');
-const path = require('path');
-const fs = require('fs');
-
-// Try to find precompiled binary first, fallback to development build
-let binding;
-try {
-    const binding_path = binary.find(path.resolve(path.join(__dirname, './package.json')));
-    binding = require(binding_path);
-} catch (err) {
-    // Fallback to development build location
-    const dev_path = path.join(__dirname, 'build', 'Release', 'zigpug.node');
-    if (fs.existsSync(dev_path)) {
-        binding = require(dev_path);
-    } else {
-        throw new Error(
-            'zig-pug native addon not found. ' +
-            'Please build it with: cd .. && zig build node'
-        );
-    }
-}
+const binding = require('./build/Release/zigpug.node');
 
 /**
- * ZigPugCompiler class - High-level API for compiling Pug templates
+ * PugCompiler class - High-level API for compiling Pug templates
  */
-class ZigPugCompiler {
+class PugCompiler {
     constructor() {
         this.context = binding.createContext();
         if (!this.context) {
@@ -40,7 +20,7 @@ class ZigPugCompiler {
      * Set a string variable in the template context
      * @param {string} key - Variable name
      * @param {string} value - String value
-     * @returns {ZigPugCompiler} - Returns this for chaining
+     * @returns {PugCompiler} - Returns this for chaining
      */
     setString(key, value) {
         if (typeof key !== 'string') {
@@ -61,7 +41,7 @@ class ZigPugCompiler {
      * Set a number variable in the template context
      * @param {string} key - Variable name
      * @param {number} value - Number value
-     * @returns {ZigPugCompiler} - Returns this for chaining
+     * @returns {PugCompiler} - Returns this for chaining
      */
     setNumber(key, value) {
         if (typeof key !== 'string') {
@@ -82,7 +62,7 @@ class ZigPugCompiler {
      * Set a boolean variable in the template context
      * @param {string} key - Variable name
      * @param {boolean} value - Boolean value
-     * @returns {ZigPugCompiler} - Returns this for chaining
+     * @returns {PugCompiler} - Returns this for chaining
      */
     setBool(key, value) {
         if (typeof key !== 'string') {
@@ -103,7 +83,7 @@ class ZigPugCompiler {
      * Set a variable (automatically detects type)
      * @param {string} key - Variable name
      * @param {string|number|boolean} value - Value of any supported type
-     * @returns {ZigPugCompiler} - Returns this for chaining
+     * @returns {PugCompiler} - Returns this for chaining
      */
     set(key, value) {
         if (typeof value === 'string') {
@@ -120,7 +100,7 @@ class ZigPugCompiler {
     /**
      * Set multiple variables from an object
      * @param {Object} variables - Object with key-value pairs
-     * @returns {ZigPugCompiler} - Returns this for chaining
+     * @returns {PugCompiler} - Returns this for chaining
      */
     setVariables(variables) {
         if (typeof variables !== 'object' || variables === null) {
@@ -171,7 +151,7 @@ class ZigPugCompiler {
  * @returns {string} - Compiled HTML
  */
 function compile(template, variables = {}) {
-    const compiler = new ZigPugCompiler();
+    const compiler = new PugCompiler();
     return compiler.render(template, variables);
 }
 
@@ -196,10 +176,8 @@ function version() {
 }
 
 module.exports = {
-    ZigPugCompiler,
+    PugCompiler,
     compile,
     compileFile,
-    version,
-    // Backward compatibility alias
-    PugCompiler: ZigPugCompiler
+    version
 };

package/index.mjs

@@ -0,0 +1,192 @@
+/**
+ * zig-pug - Pug template engine for Node.js (ES Module version)
+ * Powered by Zig and mujs
+ */
+
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { readFileSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const require = createRequire(import.meta.url);
+
+const binding = require('./build/Release/zigpug.node');
+
+/**
+ * PugCompiler class - High-level API for compiling Pug templates
+ */
+export class PugCompiler {
+    constructor() {
+        this.context = binding.createContext();
+        if (!this.context) {
+            throw new Error('Failed to create zig-pug context');
+        }
+    }
+
+    /**
+     * Set a string variable in the template context
+     * @param {string} key - Variable name
+     * @param {string} value - String value
+     * @returns {PugCompiler} - Returns this for chaining
+     */
+    setString(key, value) {
+        if (typeof key !== 'string') {
+            throw new TypeError('Key must be a string');
+        }
+        if (typeof value !== 'string') {
+            throw new TypeError('Value must be a string');
+        }
+
+        const success = binding.setString(this.context, key, value);
+        if (!success) {
+            throw new Error(`Failed to set string variable: ${key}`);
+        }
+        return this;
+    }
+
+    /**
+     * Set a number variable in the template context
+     * @param {string} key - Variable name
+     * @param {number} value - Number value
+     * @returns {PugCompiler} - Returns this for chaining
+     */
+    setNumber(key, value) {
+        if (typeof key !== 'string') {
+            throw new TypeError('Key must be a string');
+        }
+        if (typeof value !== 'number') {
+            throw new TypeError('Value must be a number');
+        }
+
+        const success = binding.setNumber(this.context, key, Math.floor(value));
+        if (!success) {
+            throw new Error(`Failed to set number variable: ${key}`);
+        }
+        return this;
+    }
+
+    /**
+     * Set a boolean variable in the template context
+     * @param {string} key - Variable name
+     * @param {boolean} value - Boolean value
+     * @returns {PugCompiler} - Returns this for chaining
+     */
+    setBool(key, value) {
+        if (typeof key !== 'string') {
+            throw new TypeError('Key must be a string');
+        }
+        if (typeof value !== 'boolean') {
+            throw new TypeError('Value must be a boolean');
+        }
+
+        const success = binding.setBool(this.context, key, value);
+        if (!success) {
+            throw new Error(`Failed to set boolean variable: ${key}`);
+        }
+        return this;
+    }
+
+    /**
+     * Set a variable (automatically detects type)
+     * @param {string} key - Variable name
+     * @param {string|number|boolean} value - Value of any supported type
+     * @returns {PugCompiler} - Returns this for chaining
+     */
+    set(key, value) {
+        if (typeof value === 'string') {
+            return this.setString(key, value);
+        } else if (typeof value === 'number') {
+            return this.setNumber(key, value);
+        } else if (typeof value === 'boolean') {
+            return this.setBool(key, value);
+        } else {
+            throw new TypeError(`Unsupported value type for key "${key}": ${typeof value}`);
+        }
+    }
+
+    /**
+     * Set multiple variables from an object
+     * @param {Object} variables - Object with key-value pairs
+     * @returns {PugCompiler} - Returns this for chaining
+     */
+    setVariables(variables) {
+        if (typeof variables !== 'object' || variables === null) {
+            throw new TypeError('Variables must be an object');
+        }
+
+        for (const [key, value] of Object.entries(variables)) {
+            this.set(key, value);
+        }
+
+        return this;
+    }
+
+    /**
+     * Compile a Pug template to HTML
+     * @param {string} template - Pug template string
+     * @returns {string} - Compiled HTML
+     */
+    compile(template) {
+        if (typeof template !== 'string') {
+            throw new TypeError('Template must be a string');
+        }
+
+        const html = binding.compile(this.context, template);
+        if (!html) {
+            throw new Error('Failed to compile template');
+        }
+
+        return html;
+    }
+
+    /**
+     * Compile a template with variables in one call
+     * @param {string} template - Pug template string
+     * @param {Object} variables - Variables to set before compiling
+     * @returns {string} - Compiled HTML
+     */
+    render(template, variables = {}) {
+        this.setVariables(variables);
+        return this.compile(template);
+    }
+}
+
+/**
+ * Convenience function to compile a template with variables
+ * @param {string} template - Pug template string
+ * @param {Object} variables - Variables for the template
+ * @returns {string} - Compiled HTML
+ */
+export function compile(template, variables = {}) {
+    const compiler = new PugCompiler();
+    return compiler.render(template, variables);
+}
+
+/**
+ * Convenience function to compile a template from a file
+ * @param {string} filename - Path to the Pug template file
+ * @param {Object} variables - Variables for the template
+ * @returns {string} - Compiled HTML
+ */
+export function compileFile(filename, variables = {}) {
+    const template = readFileSync(filename, 'utf8');
+    return compile(template, variables);
+}
+
+/**
+ * Get the zig-pug version
+ * @returns {string} - Version string
+ */
+export function version() {
+    return binding.version();
+}
+
+// Default export for compatibility
+export default {
+    PugCompiler,
+    compile,
+    compileFile,
+    version
+};

package/package.json

@@ -1,20 +1,21 @@
 {
   "name": "zig-pug",
-  "version": "0.2.0",
-  "description": "High-performance Pug template engine powered by Zig and mujs - Native N-API addon with ES5.1 JavaScript support",
+  "version": "0.3.1",
+  "description": "High-performance Pug template engine powered by Zig and mujs. Native N-API addon with ES5.1 JavaScript support, full UTF-8 (emoji, accents), documentation comments (//!), and fast compilation. Compatible with Node.js and Bun.",
+  "type": "commonjs",
   "main": "index.js",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "require": "./index.js"
+    }
+  },
   "scripts": {
-    "install": "node-pre-gyp install --fallback-to-build || (cd .. && zig build node)",
-    "build": "cd .. && zig build node",
-    "build:from-source": "cd .. && zig build node",
-    "rebuild": "node-gyp rebuild && npm run postbuild",
-    "postbuild": "cp ../zig-out/nodejs/libzigpug.* build/Release/ 2>/dev/null || true",
-    "clean": "node-gyp clean && rm -rf ../zig-out/nodejs lib/binding",
-    "test": "LD_LIBRARY_PATH=../zig-out/nodejs:$LD_LIBRARY_PATH node test/test.js",
-    "example": "LD_LIBRARY_PATH=../zig-out/nodejs:$LD_LIBRARY_PATH node example.js",
-    "package": "node-pre-gyp package",
-    "upload": "node-pre-gyp publish",
-    "upload:github": "node scripts/upload-binary.js",
+    "install": "node-gyp rebuild",
+    "build": "node-gyp configure build",
+    "rebuild": "node-gyp rebuild",
+    "clean": "node-gyp clean",
+    "test": "node test/test.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -40,11 +41,22 @@
     "view-engine",
     "express",
     "jade",
-    "haml"
+    "haml",
+    "utf-8",
+    "utf8",
+    "unicode",
+    "emoji",
+    "i18n",
+    "internationalization",
+    "multilingual",
+    "spanish",
+    "portuguese",
+    "french",
+    "german"
   ],
   "author": {
-    "name": "carlos-sweb",
-    "url": "https://github.com/carlos-sweb"
+    "name": "zig-pug contributors",
+    "url": "https://github.com/carlos-sweb/zig-pug/graphs/contributors"
   },
   "license": "MIT",
   "repository": {
@@ -59,23 +71,19 @@
   "engines": {
     "node": ">=14.0.0"
   },
-  "dependencies": {
-    "@mapbox/node-pre-gyp": "^1.0.11"
-  },
+  "dependencies": {},
   "devDependencies": {
-    "node-gyp": "^10.0.0",
-    "aws-sdk": "^2.1691.0"
+    "node-gyp": "^10.0.0"
   },
   "gypfile": true,
   "binary": {
     "module_name": "zigpug",
-    "module_path": "./lib/binding/{configuration}/{node_abi}-{platform}-{arch}",
-    "remote_path": "./{version}",
-    "package_name": "{module_name}-v{version}-{node_abi}-{platform}-{arch}.tar.gz",
+    "module_path": "./build/Release/",
     "host": "https://github.com/carlos-sweb/zig-pug/releases/download/"
   },
   "files": [
     "index.js",
+    "index.mjs",
     "binding.c",
     "binding.gyp",
     "common.gypi",