app-builder

Files (5)

• SKILL.md
• SKILL.md · agent-builder/
• SKILL.md · data-builder/
• SKILL.md · game-builder/
• SKILL.md · platform-api/

SKILL.md (first lines)

# App Builder

You can build **Dench Apps** — self-contained web applications that run inside DenchClaw's workspace. Apps appear in the sidebar with their own icon and name, and open as tabs in the main content area. They run in a sandboxed iframe with `allow-same-origin allow-scripts allow-popups allow-forms`.

---

## Table of Contents

1. [App Structure](#app-structure)
2. [Manifest Reference](#manifest-reference)
3. [Bridge API Overview](#bridge-api-overview)
4. [Theme & Styling System](#theme--styling-system)
5. [Loading External Libraries via CDN](#loading-external-libraries-via-cdn)
6. [Multi-File App Organization](#multi-file-app-organization)
7. [Asset Management](#asset-management)
8. [Performance & Best Practices](#performance--best-practices)
9. [Error Handling Patterns](#error-handling-patterns)
10. [Creating an App — Step by Step Checklist](#creating-an-app--step-by-step-checklist)
11. [Child Skills](#child-skills)

---

## App Structure

Every app is a folder ending in `.dench.app/`. The default location is `{{WORKSPACE_PATH}}/apps/`, but apps can live anywhere in the workspace.

```
apps/
  my-app.dench.app/
    .dench.yaml          # Required manifest
    index.html           # Entry point
    style.css            # Styles (optional, can inline)
    app.js               # Logic (optional, can inline)
    assets/              # Images, sounds, models, etc.
      sprite.png
      bg-music.mp3
    lib/                 # Vendored libraries (optional)
      p5.min.js
```

### Critical Rules

- The folder name MUST end with `.dench.app`
- The `.dench.yaml` manifest is REQUIRED inside every `.dench.app` folder
- The entry HTML file gets the bridge SDK (`window.dench`) auto-injected before `</head>`
- All file paths within the app are relative to the `.dench.app` folder root
- The app is served at `/api/apps/serve/<appPath>/<filePath>` — relative references (CSS, JS, images) resolve correctly
- Apps run in an iframe sandbox: `allow-same-origin allow-scripts allow-popups allow-forms`

---

## Manifest Reference

Every `.dench.app` folder MUST contain a `.dench.yaml` manifest.

### Full Schema

```yaml
name: "My App" # Required. Display name shown in sidebar and tab bar
description: "What this app does" # Optional. Shown in tooltips and app info
icon: "gamepad-2" # Optional. Lucide icon name OR relative path to image
version: "1.0.0" # Optional. Shown as badge in app header
author: "agent" # Optional. Creator attribution
entry: "index.html" # Optional. Main entry point (default: index.html)
runtime: "static" # Optional. static | esbuild | build (default: static)

display: "full" # Optional. "full" (default) | "widget"
widget: # Only used when display: "widget"
  width: 2 # Grid columns (1-4)
  height: 1 # Grid rows (1-4)
  refreshInterval: 60 # Auto-refresh seconds (optional)

permissions: # Optional. List of bridge API permissions
  - database # db.query (SELECT only)
  - database:write # db.execute (INSERT/UPDATE/DELETE/CREATE)
  - objects # objects.* CRUD on workspace tables
  - files # files.read, files.list
  - files:write # files.write, files.delete, files.mkdir
  - agent # chat.*, agent.send, tool.register, memory.get
  - ui # ui.toast, ui.navigate, ui.openEntry, etc.
  - store # store.* per-app KV storage
  - http # http.fetch CORS proxy
  - events # events.on/off real-time subscriptions
  - apps # apps.send/on inter-app messaging
  - cron # cron.schedule/list/cancel
  - webhooks # webhooks.register/on
  - clipboard # clipboard.read/write

tools: # Optional. Expose app functions as agent-invokable tools
  - name: "my-tool"
    description: "What this tool does"
    inputSchema:
      type: object
      properties:
        input: { type: string }
      required: ["input"]
```

### Runtime Modes

| Mode      | When to Use                                                       | How It Works                                                                                       |
| --------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `static`  | Vanilla HTML/CSS/JS apps, CDN-loaded libraries, games, dashboards | Serves files directly. **Use this by default for everything.**                                     |
| `esbuild` | React/TSX apps without npm dependencies                           | Server-side esbuild transpiles JSX/TSX on load. Requires `esbuild.entry` and `esbuild.jsx` fields. |
| `build`   | Complex apps with npm dependencies (rare)                         | Runs `build.install` then `build.command`. Serves from `build.output` directory.                   |

**Always default to `static` runtime.** It handles p5.js, Three.js, D3.js, Chart.js, and any CDN-loaded library perfectly. Only use `esbuild` or `build` when the user explicitly asks for React/TSX or npm-based tooling.

### Icon Support

The `icon` field accepts:

1. **A Lucide icon name** (string): `"gamepad-2"`, `"bar-chart-3"`, `"users"`, `"rocket"`, `"calculator"`, `"box"`, `"palette"`
2. **A relative path** to a square image file: `"icon.png"`, `"assets/logo.svg"`

Supported image formats: PNG, SVG, JPG, JPEG, WebP. Use square aspect ratio (128x128px or larger).

### Choosing Permissions

From orianna-ai/DenchClaw, MIT.

More from orianna-ai/DenchClaw