npm - enigmatic - Versions diffs - 0.33.0 → 0.35.0 - Mend

enigmatic 0.33.0 → 0.35.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/{CLIENT_JS_DOCS.md → README.md} +163 -36
package/bin/enigmatic.js +3 -0
package/client/public/AGENTS.md +314 -0
package/client/public/client.js +125 -0
package/client/public/custom.js +34 -0
package/client/public/index.html +197 -0
package/clientserver.png +0 -0
package/package.json +7 -9
package/server/bun-server.js +119 -0
package/__tests__/e2.test.js +0 -310
package/__tests__/jest.config.js +0 -7
package/__tests__/jest.setup.js +0 -9
package/bun-server.js +0 -130
package/public/client.css +0 -286
package/public/client.js +0 -80
package/public/custom.js +0 -29
package/public/index.html +0 -45
package/public/index2.html +0 -9
package/public/theme.css +0 -9

package/{CLIENT_JS_DOCS.md → README.md} RENAMED Viewed

@@ -1,4 +1,108 @@
-# client.js Documentation
+# Enigmatic
+![Version](https://img.shields.io/npm/v/enigmatic)
+A lightweight client-side JavaScript library for DOM manipulation, reactive state management, and API interactions, with an optional Bun server for backend functionality.
+## Architecture
+![Client-Server Architecture](clientserver.png)
+The diagram above shows the interaction between the client (browser), Bun server, and external services (Auth0 and Cloudflare R2/S3).
+## Quick Start
+### Using client.js via CDN
+Include `client.js` in any HTML file using the unpkg CDN:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script src="https://unpkg.com/enigmatic"></script>
+  <script src="https://unpkg.com/enigmatic/client/public/custom.js"></script>
+  <script>
+    window.api_url = 'https://your-server.com';
+    window.state.message = 'Hello World';
+  </script>
+</head>
+<body>
+  <hello-world data="message"></hello-world>
+</body>
+</html>
+```
+**Note:** Use `enigmatic@0.35.0` (or latest) in the URL to pin a version.
+### Using the Bun Server
+The Bun server provides a complete backend with:
+- **Key-value storage** – Per-user KV persisted as append-only JSONL (`server/kv/{user}.jsonl`) with `update`/`delete` actions and timestamps
+- **File storage** – Per-user files via Cloudflare R2 (or S3-compatible API)
+- **Authentication** – Auth0 OAuth2 login/logout
+- **Static files** – Served from `client/public/`
+#### Installation
+1. Install [Bun](https://bun.sh):
+   ```bash
+   curl -fsSL https://bun.sh/install | bash
+   ```
+2. Install dependencies (if any):
+   ```bash
+   bun install
+   ```
+3. TLS certificates: place `cert.pem` and `key.pem` in `server/certs/` for HTTPS (required for Auth0 in production).
+#### Environment Variables
+Create a `.env` file in the project root (or set env vars):
+```bash
+# Auth0
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_CLIENT_ID=your-client-id
+AUTH0_CLIENT_SECRET=your-client-secret
+# Cloudflare R2 (optional, for file storage)
+CLOUDFLARE_ACCESS_KEY_ID=your-access-key-id
+CLOUDFLARE_SECRET_ACCESS_KEY=your-secret-access-key
+CLOUDFLARE_BUCKET_NAME=your-bucket-name
+CLOUDFLARE_PUBLIC_URL=https://your-account-id.r2.cloudflarestorage.com
+```
+#### Running the Server
+```bash
+npm start
+# or
+npx enigmatic
+# or with hot reload
+npm run hot
+```
+Server runs at **https://localhost:3000** (HTTPS is required for Auth0 cookies).
+#### Server Endpoints
+| Method   | Path       | Description |
+|----------|------------|-------------|
+| GET      | `/`        | Serves `client/public/index.html` |
+| GET      | `/index.html`, `/*.js`, etc. | Static files from `client/public/` |
+| GET      | `/login`   | Redirects to Auth0 login |
+| GET      | `/callback`| Auth0 OAuth callback |
+| GET      | `/logout`  | Logs out and clears session |
+| GET      | `/me`      | Current user or 401 (no auth) |
+| GET      | `/{key}`   | KV get (auth required) |
+| POST     | `/{key}`   | KV set (auth required) |
+| DELETE   | `/{key}`   | KV delete (auth required) |
+| PUT      | `/{key}`   | Upload file to R2 (auth required) |
+| PURGE    | `/{key}`   | Delete file from R2 (auth required) |
+| PROPFIND | `/`        | List R2 files (auth required) |
+| PATCH    | `/{key}`   | Download file from R2 (auth required) |
 ## Overview
@@ -36,13 +140,15 @@ Configures the base URL for all API requests. Modify this to point to your serve
 - Set a property: `window.state.myKey = 'value'`
 - Elements with `data="myKey"` attribute are automatically updated
 - The system looks for custom element handlers in `window.custom[tagName]`
+- Only elements with matching custom element handlers are updated
 - Supports both function and object-based custom elements
 **Example:**
 ```html
-<div data="message">Initial</div>
+<my-element data="message">Initial</my-element>
 <script>
-  window.state.message = "Updated!"; // Automatically updates the div
+  window.custom['my-element'] = (data) => `<div>${data}</div>`;
+  window.state.message = "Updated!"; // Automatically updates the element
 </script>
 ```
@@ -167,9 +273,19 @@ window.logout();
 **Behavior:** Sets `window.location.href` to `{api_url}/logout`
+#### `window.me()`
+Returns the current user if authenticated, or `null` if not (e.g. 401).
+```javascript
+const user = await window.me();
+// user is { sub, email, ... } or null
+```
+**Endpoint:** `GET {api_url}/me` (with credentials)
 ## Custom Elements System
-Custom elements are defined in `window.custom` object and automatically initialized when the DOM loads.
+Custom elements are defined in `window.custom` object and automatically initialized when the DOM loads or when elements are added dynamically.
 ### Initialization
@@ -178,6 +294,17 @@ The library automatically:
 2. Iterates through all keys in `window.custom`
 3. Finds all matching HTML elements by tag name
 4. Calls the custom element handler and sets `innerHTML`
+5. Watches for new elements added to the DOM via MutationObserver and initializes them automatically
+### Proxy Behavior
+`window.custom` is a Proxy that automatically initializes matching elements when you add a new custom element definition:
+```javascript
+// Adding a new custom element automatically initializes all matching elements in the DOM
+window.custom['my-element'] = (data) => `<div>${data}</div>`;
+// All <my-element> tags are immediately initialized
+```
 ### Defining Custom Elements
@@ -196,12 +323,15 @@ window.custom = {
 <my-element></my-element>
 ```
-When `window.state.myKey = 'value'` is set and an element has `data="myKey"`:
+When used with reactive state, the function receives the state value:
 ```html
 <my-element data="myKey"></my-element>
+<script>
+  window.state.myKey = 'value'; // Function is called with 'value'
+</script>
 ```
-The function receives the state value as the first parameter.
+The function receives the state value as the first parameter. If no state value is set, it receives `undefined`.
 #### Object-based Custom Element
@@ -267,37 +397,18 @@ window.get('key').catch(err => console.error(err));
 <!DOCTYPE html>
 <html>
 <head>
-  <script src="custom.js"></script>
-  <script src="client.js"></script>
+  <script src="https://unpkg.com/enigmatic"></script>
+  <script src="https://unpkg.com/enigmatic/client/public/custom.js"></script>
+  <script>
+    window.api_url = window.api_url || window.location.origin;
+    window.state.message = 'World';
+  </script>
 </head>
 <body>
-  <!-- Custom element -->
+  <hello-world data="message"></hello-world>
   <file-widget></file-widget>
-  <!-- Reactive state element -->
-  <div data="message">Initial</div>
   <script>
-    // Set reactive state
-    window.state.message = "Hello World";
-    // Use API functions
-    (async () => {
-      await window.set('test', 'value');
-      const value = await window.get('test');
-      console.log(value);
-      // Upload file
-      const fileInput = document.querySelector('input[type="file"]');
-      fileInput.onchange = async (e) => {
-        const file = e.target.files[0];
-        await window.put(file.name, file);
-      };
-      // List files
-      const files = await window.list();
-      console.log(files);
-    })();
+    window.me().then(u => console.log(u ? 'Logged in as ' + u.email : 'Not logged in'));
   </script>
 </body>
 </html>
@@ -305,18 +416,34 @@ window.get('key').catch(err => console.error(err));
 ## Dependencies
-- Requires `custom.js` to be loaded before `client.js` if using custom elements
-- Requires a backend server that implements the API endpoints
+- Requires a backend server that implements the API endpoints (or use the included Bun server)
 - Requires browser support for:
   - `fetch` API
   - `Proxy` API
   - `Blob` API
   - `URL.createObjectURL`
+  - `MutationObserver` API
+**Note:** Load `client.js` first, then your custom element definitions (e.g. `custom.js`); the Proxy initializes elements when definitions are assigned.
 ## Notes
 - All API functions automatically encode keys using `encodeURIComponent`
 - The `window.download()` function uses PATCH method internally (browsers don't support custom HTTP methods)
-- Custom elements are initialized once on page load; use `location.reload()` to refresh
+- Custom elements are automatically initialized:
+  - On page load (when DOM is ready)
+  - When new custom element definitions are added to `window.custom`
+  - When new matching elements are added to the DOM (via MutationObserver)
 - The reactive state system only updates elements with matching `data` attributes
 - Custom element handlers can be async functions
+- When a custom element has a `data` attribute, it automatically reads from `window.state[dataValue]` if no explicit value is provided
+## Development
+- **Start server:** `npm start` or `npx enigmatic`
+- **Hot reload:** `npm run hot`
+- **Client:** Load `client.js` from unpkg or from `client/public/client.js` when serving locally. Load `custom.js` (or your definitions) after `client.js`; set `window.api_url` before making API calls.
+## License
+MIT

package/bin/enigmatic.js ADDED Viewed

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+import config from "../server/bun-server.js";
+Bun.serve(config);

package/client/public/AGENTS.md ADDED Viewed

@@ -0,0 +1,314 @@
+# Custom Web Components Instructions for LLMs
+## Overview
+When users request web components to be created, you MUST use the `window.custom` system. You can see examples at https://unpkg.com/enigmatic/client/public/custom.js or in the repo at `client/public/custom.js`. This system allows you to define custom HTML elements that automatically render and can be reactive to state changes.
+## System Architecture
+The custom component system works by:
+1. Defining components in `window.custom` object
+2. Using custom HTML tags in the DOM (e.g., `<my-component></my-component>`)
+3. Components automatically initialize when the DOM loads or when elements are added
+4. Components can be reactive to `window.state` changes via `data` attributes
+## Component Definition Format
+### Format 1: Function-Based Component (Simple)
+**Use this format for simple components that just render HTML:**
+```javascript
+window.custom = {
+  "mycomponent": (data) => {
+    // data is the value from window.state if element has data="key" attribute
+    // If no data attribute, data will be undefined
+    return `<div>Your HTML here: ${data || 'default'}</div>`;
+  }
+};
+```
+**Example from custom.js:**
+```javascript
+window.custom = {
+  "hello-world": (data) => `Hello ${data}`,
+};
+```
+**HTML Usage:**
+```html
+<hello-world></hello-world>
+<!-- or with reactive state -->
+<hello-world data="message"></hello-world>
+<script>
+  window.state.message = "World"; // Component updates automatically
+</script>
+```
+### Format 2: Object-Based Component (Advanced)
+**Use this format when you need methods, properties, or more complex logic:**
+```javascript
+window.custom = {
+  "component-name": {
+    // Optional helper methods
+    prop: (data) => `Processed: ${data}`,
+    // Required: render method that returns HTML string
+    render: function(data) {
+      // Use 'this' to access other methods/properties
+      return `<div>${this.prop(data)}</div>`;
+    }
+  }
+};
+```
+**Example from custom.js:**
+```javascript
+window.custom = {
+  "hello-world-2": {
+    prop: (data) => `${data} World`,
+    render: function(data) {
+      return this.prop(data);
+    }
+  }
+};
+```
+**HTML Usage:**
+```html
+<hello-world-2 data="greeting"></hello-world-2>
+<script>
+  window.state.greeting = "Hello"; // Component updates automatically
+</script>
+```
+### Format 3: Async Component
+**Use this format when you need to fetch data or perform async operations:**
+```javascript
+window.custom = {
+  "async-component": async () => {
+    try {
+      const data = await window.get('some-key');
+      // Or use other API functions: window.list(), window.set(), etc.
+      return `<div>${JSON.stringify(data)}</div>`;
+    } catch (err) {
+      return `<div>Error: ${err.message}</div>`;
+    }
+  }
+};
+```
+**Example from custom.js:**
+```javascript
+window.custom = {
+  "file-widget": async () => {
+    try {
+      const list = await window.list();
+      // Render file list with styles and interactive elements
+      return `<div>...</div>`;
+    } catch (err) {
+      return `<div>Error occurred</div>`;
+    }
+  }
+};
+```
+## Key Rules and Patterns
+### 1. Component Names
+- Use kebab-case (e.g., `"my-component"`, `"file-widget"`)
+- Must match the HTML tag name exactly (case-insensitive)
+- Example: `window.custom["my-component"]` → `<my-component></my-component>`
+### 2. Return Value
+- Components MUST return a string containing HTML
+- Can include inline `<style>` tags for component-specific styles
+- Can include inline event handlers using `onclick`, `onchange`, etc.
+### 3. Reactive State Integration
+- Components automatically receive state values when element has `data="key"` attribute
+- When `window.state.key = value` is set, all elements with `data="key"` are re-rendered
+- Access state value as the first parameter: `(data) => ...` or `render: function(data) { ... }`
+### 4. Async Operations
+- Use `async` functions when you need to fetch data
+- Use `window.get()`, `window.set()`, `window.list()`, `window.put()`, `window.delete()`, `window.purge()`, `window.me()`, `window.download()`, etc. for API calls (all use `window.api_url`)
+- Always wrap async operations in try-catch for error handling
+### 5. Styling
+- Include styles inline using `<style>` tags within the returned HTML
+- Use scoped class names (e.g., `.w-c`, `.w-i`) to avoid conflicts
+- Keep styles minimal and component-specific
+### 6. Event Handlers
+- Use inline event handlers: `onclick="..."`, `onchange="..."`
+- Can call `window` API functions directly: `onclick="window.download('file.txt')"`
+- For async operations, wrap in IIFE: `onclick="(async()=>{await window.purge('file');location.reload()})()"`
+## Complete Examples
+### Example 1: Simple Counter Component
+```javascript
+window.custom = {
+  "counter": (data) => {
+    const count = data || 0;
+    return `
+      <div style="padding: 20px; text-align: center;">
+        <h2>Count: ${count}</h2>
+        <button onclick="window.state.count = (window.state.count || 0) + 1">+</button>
+        <button onclick="window.state.count = (window.state.count || 0) - 1">-</button>
+      </div>
+    `;
+  }
+};
+```
+**HTML:**
+```html
+<counter data="count"></counter>
+<script>
+  window.state.count = 0;
+</script>
+```
+### Example 2: Data Display Component
+```javascript
+window.custom = {
+  "data-display": async () => {
+    try {
+      const data = await window.get('user-data');
+      return `
+        <div style="padding: 15px; border: 1px solid #ddd; border-radius: 5px;">
+          <h3>User Data</h3>
+          <pre>${JSON.stringify(data, null, 2)}</pre>
+        </div>
+      `;
+    } catch (err) {
+      return `<div style="color: red;">Error loading data: ${err.message}</div>`;
+    }
+  }
+};
+```
+**HTML:**
+```html
+<data-display></data-display>
+```
+### Example 3: Form Component with Object Methods
+```javascript
+window.custom = {
+  "contact-form": {
+    validate: (email) => email && email.includes('@'),
+    render: function(data) {
+      const email = data?.email || '';
+      const isValid = this.validate(email);
+      return `
+        <style>
+          .form-container { padding: 20px; max-width: 400px; }
+          .form-input { width: 100%; padding: 8px; margin: 5px 0; }
+          .form-submit { background: #007bff; color: white; padding: 10px 20px; border: none; cursor: pointer; }
+        </style>
+        <div class="form-container">
+          <input type="email" class="form-input"
+                 placeholder="Email"
+                 value="${email}"
+                 onchange="window.state.formData = {...(window.state.formData || {}), email: this.value}">
+          <button class="form-submit"
+                  onclick="alert('Form submitted!')"
+                  ${!isValid ? 'disabled' : ''}>
+            Submit
+          </button>
+        </div>
+      `;
+    }
+  }
+};
+```
+**HTML:**
+```html
+<contact-form data="formData"></contact-form>
+<script>
+  window.state.formData = { email: '' };
+</script>
+```
+## When to Use Each Format
+- **Function format**: Simple components, static content, or when you only need the data parameter
+- **Object format**: When you need helper methods, want to organize code better, or need `this` context
+- **Async format**: When you need to fetch data from APIs, perform async operations, or load external resources
+## Important Notes
+1. **Always return HTML strings** - Components must return valid HTML strings
+2. **Handle errors** - Wrap async operations in try-catch blocks
+3. **Use kebab-case** - Component names must be in kebab-case to match HTML tag names
+4. **State reactivity** - Use `data="key"` attribute to make components reactive to `window.state[key]`
+5. **Auto-initialization** - Components automatically initialize when:
+   - DOM loads
+   - Component is added to `window.custom`
+   - New matching elements are added to the DOM
+## Common Patterns
+### Pattern: Loading State
+```javascript
+window.custom = {
+  "loading-component": async () => {
+    try {
+      const data = await window.get('data');
+      return data ? `<div>${data}</div>` : '<div>No data</div>';
+    } catch (err) {
+      return `<div>Error: ${err.message}</div>`;
+    }
+  }
+};
+```
+### Pattern: Error Handling
+```javascript
+window.custom = {
+  "safe-component": async () => {
+    try {
+      const result = await window.list();
+      return `<div>Success: ${result.length} items</div>`;
+    } catch (err) {
+      return `<div style="color: red;">Error: ${err.message}</div>`;
+    }
+  }
+};
+```
+### Pattern: Conditional Rendering
+```javascript
+window.custom = {
+  "conditional": (data) => {
+    if (!data) return '<div>No data</div>';
+    if (data.error) return `<div>Error: ${data.error}</div>`;
+    return `<div>Data: ${data.value}</div>`;
+  }
+};
+```
+## Summary
+When creating web components:
+1. Define them in `window.custom` object
+2. Use kebab-case names matching HTML tag names
+3. Return HTML strings (can include styles and event handlers)
+4. Use function format for simple components
+5. Use object format with `render` method for complex components
+6. Use async functions when fetching data
+7. Make components reactive by using `data="key"` attributes
+8. Always handle errors in async components