@zenuml/core 3.32.7 → 3.34.0

package/.kiro/hooks/README.md

@@ -0,0 +1,38 @@
+# Kiro Agent Hooks
+
+This directory contains custom hooks that automatically execute when specific events occur in Kiro.
+
+## Session Sound Notification Hook
+
+**File:** `session-sound-notification.json` and `session-sound-notification.js`
+
+**Purpose:** Plays system sounds to notify you when:
+
+- An AI session completes
+- User input is required to continue
+- An error occurs
+
+**Sounds Used (macOS):**
+
+- **Session Complete:** Glass.aiff - A pleasant chime when tasks finish
+- **Input Required:** Sosumi.aiff - An attention-getting sound when you need to respond
+- **Error:** Basso.aiff - A distinctive sound for errors
+- **Default:** Ping.aiff - Fallback sound
+
+**Configuration:**
+The hook is enabled by default and will auto-execute. You can disable it by setting `"enabled": false` in the JSON configuration file.
+
+**Platform Notes:**
+
+- Currently optimized for macOS using the `afplay` command
+- Uses built-in system sounds located in `/System/Library/Sounds/`
+- For other platforms, the sound files and playback command would need to be adjusted
+
+## Managing Hooks
+
+You can:
+
+1. View current hooks in the Kiro Explorer under "Agent Hooks"
+2. Use Command Palette → "Open Kiro Hook UI" to create new hooks
+3. Edit hook files directly in this directory
+4. Enable/disable hooks by modifying the `enabled` property

package/.kiro/hooks/session-sound-notification.js

@@ -0,0 +1,44 @@
+/**
+ * Session Sound Notification Hook
+ * Plays a sound when sessions end or user input is required
+ */
+
+const playSound = (soundType = 'default') => {
+  // For macOS, we can use the 'afplay' command to play system sounds
+  const sounds = {
+    default: '/System/Library/Sounds/Ping.aiff',
+    complete: '/System/Library/Sounds/Glass.aiff',
+    attention: '/System/Library/Sounds/Sosumi.aiff',
+    error: '/System/Library/Sounds/Basso.aiff'
+  };
+  
+  const soundFile = sounds[soundType] || sounds.default;
+  
+  try {
+    // Use afplay to play the sound on macOS
+    require('child_process').exec(`afplay "${soundFile}"`, (error) => {
+      if (error) {
+        console.log('Could not play sound:', error.message);
+      }
+    });
+  } catch (err) {
+    console.log('Sound playback failed:', err.message);
+  }
+};
+
+module.exports = {
+  onSessionEnd: () => {
+    console.log('🔊 Session completed - playing completion sound');
+    playSound('complete');
+  },
+  
+  onUserInputRequired: () => {
+    console.log('🔊 User input needed - playing attention sound');
+    playSound('attention');
+  },
+  
+  onError: () => {
+    console.log('🔊 Error occurred - playing error sound');
+    playSound('error');
+  }
+};

package/.kiro/hooks/session-sound-notification.json

@@ -0,0 +1,23 @@
+{
+  "name": "Session Sound Notification",
+  "description": "Plays a sound when a session ends or user input is needed",
+  "triggers": [
+    {
+      "event": "session.end",
+      "description": "Triggered when an AI session completes"
+    },
+    {
+      "event": "user.input.required",
+      "description": "Triggered when the AI needs user input to continue"
+    }
+  ],
+  "actions": [
+    {
+      "type": "system.sound",
+      "sound": "notification",
+      "description": "Play system notification sound"
+    }
+  ],
+  "enabled": true,
+  "autoExecute": true
+}

package/DEPLOYMENT.md

@@ -0,0 +1,62 @@
+# ZenUML Web Renderer Deployment
+
+This document describes the deployment process for the ZenUML Web Renderer to Cloudflare Pages.
+
+## Deployment Strategy
+
+- **Production**: Deploys from `main` branch to `zenuml-web-renderer` project
+- **Staging**: Deploys from any non-main branch to `zenuml-web-renderer-staging` project
+
+## GitHub Actions Workflow
+
+The deployment is automated through GitHub Actions (`.github/workflows/cloudflare-pages.yml`):
+
+1. **Triggers**: 
+   - Push to `main` or `feat/public-renderer` branches
+   - Pull requests to `main` branch
+   - Only when relevant files are changed (renderer.html, public/**, src/**, etc.)
+
+2. **Build Process**:
+   - Install dependencies with pnpm
+   - Build the site using `pnpm build:site`
+   - Deploy to appropriate Cloudflare Pages project
+
+## Required Secrets
+
+Add these secrets to your GitHub repository settings:
+
+- `CLOUDFLARE_API_TOKEN`: Cloudflare API token with Pages permissions
+- `CLOUDFLARE_ACCOUNT_ID`: Your Cloudflare account ID
+
+## Manual Deployment
+
+You can also deploy manually using wrangler:
+
+```bash
+# Deploy to staging
+pnpm pages:deploy:staging
+
+# Deploy to production  
+pnpm pages:deploy
+```
+
+## Project Structure
+
+- `renderer.html`: Main renderer page (root level)
+- `public/renderer.html`: Copy of renderer page for static hosting
+- `dist/`: Build output directory (created by `pnpm build:site`)
+- `wrangler.toml`: Cloudflare configuration
+
+## URLs
+
+- **Production**: `https://zenuml-web-renderer.pages.dev`
+- **Staging**: `https://zenuml-web-renderer-staging.pages.dev`
+
+## Usage
+
+Once deployed, you can use the renderer by visiting:
+- `https://your-domain.pages.dev/renderer.html`
+- `https://your-domain.pages.dev/` (if configured as index)
+
+Future URL parameter support will allow:
+- `https://your-domain.pages.dev/renderer.html?code=<base64-encoded-zenuml>`

package/README.md

@@ -19,7 +19,7 @@ You can use it ZenUML on your favorite platforms and applications:
 # Integrations
 
 ZenUML can be integrated with your favorite tools and platforms as a library or an embeddable widget.
-Please follow the [integration guide](./docs/asciidoc/integration-guide.adoc) for detailed steps.
+Please follow the [integration tutorial](./TUTORIAL.md) for detailed steps.
 
 # Development
 

package/TUTORIAL.md

@@ -0,0 +1,116 @@
+
+# ZenUML Integration Tutorial
+
+This tutorial provides a comprehensive guide on how to integrate ZenUML into your applications. There are two primary methods for integration: as a library or as an embedded iframe.
+
+## 1. As a Library
+
+This is the most flexible method, allowing for deep integration with your application.
+
+### Installation
+
+First, add the `@zenuml/core` package to your project:
+
+```bash
+npm install @zenuml/core
+```
+
+or
+
+```bash
+yarn add @zenuml/core
+```
+
+### Usage
+
+The main entry point of the library is the `ZenUml` class. Here's a basic example of how to use it:
+
+```javascript
+import ZenUml from '@zenuml/core';
+
+// 1. Get the container element
+const el = document.getElementById('zenuml-container');
+
+// 2. Create a new instance of ZenUml
+const zenUml = new ZenUml(el);
+
+// 3. Render a diagram
+const code = 'A->B: message';
+const config = {
+  theme: 'default',
+};
+zenUml.render(code, config);
+```
+
+### Configuration
+
+The `render` method accepts a configuration object with the following properties:
+
+- `theme`: The name of the theme to use. A list of available themes can be found in the documentation.
+- `enableScopedTheming`: A boolean that indicates whether to scope the theme to the container element. This is useful when you have multiple diagrams on the same page with different themes.
+- `onThemeChange`: A callback function that is called when the theme is changed.
+- `enableMultiTheme`: A boolean that indicates whether to enable multi-theme support.
+- `stickyOffset`: A number that indicates the offset for the sticky header.
+- `onContentChange`: A callback function that is called when the content of the diagram is changed.
+- `onEventEmit`: A callback function that is called when an event is emitted from the diagram.
+- `mode`: The rendering mode. Can be `RenderMode.Dynamic` or `RenderMode.Static`.
+
+### Example
+
+Here's a more advanced example that uses some of the configuration options:
+
+```javascript
+import ZenUml from '@zenuml/core';
+
+const el = document.getElementById('zenuml-container');
+const zenUml = new ZenUml(el);
+
+const code = `
+  // This is a comment
+  A->B: synchronous message
+  B-->A: asynchronous message
+`;
+
+const config = {
+  theme: 'blue',
+  enableScopedTheming: true,
+  onContentChange: (newCode) => {
+    console.log('Diagram code changed:', newCode);
+  },
+};
+
+zenUml.render(code, config);
+```
+
+### Exporting Diagrams
+
+You can export diagrams to PNG and SVG formats. The `ZenUml` class provides the following methods for exporting:
+
+- `getPng()`: Returns a promise that resolves to a PNG data URL.
+- `getSvg()`: Returns a promise that resolves to an SVG data URL.
+
+Here's an example of how to use these methods:
+
+```javascript
+import ZenUml from '@zenuml/core';
+
+const el = document.getElementById('zenuml-container');
+const zenUml = new ZenUml(el);
+
+const code = 'A->B: message';
+
+async function exportDiagram() {
+  await zenUml.render(code, { theme: 'default' });
+  const png = await zenUml.getPng();
+  // Do something with the PNG data URL
+  console.log(png);
+
+  const svg = await zenUml.getSvg();
+  // Do something with the SVG data URL
+  console.log(svg);
+}
+
+exportDiagram();
+```
+
+This tutorial should provide you with a solid foundation for integrating ZenUML into your applications. For more detailed information, please refer to the official documentation.