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
2. Manifest Reference
3. Bridge API Overview
4. Theme & Styling System
5. Loading External Libraries via CDN
6. Multi-File App Organization
7. Asset Management
8. Performance & Best Practices
9. Error Handling Patterns
10. Creating an App — Step by Step Checklist
11. 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

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

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

Only request what you need. A game with no data access needs no permissions at all.

Bridge API Overview

The bridge SDK is auto-injected into every app's HTML. It provides window.dench with the following namespaces. All methods return Promises with a 30-second timeout.

Core APIs (no child skill needed)

// Get the app's own parsed manifest
const manifest = await dench.app.getManifest();

// Get current DenchClaw UI theme
const theme = await dench.app.getTheme();
// Returns: "dark" or "light"

File Access (files / files:write permission)

// Read a workspace file
const content = await dench.files.read("path/to/file.md");

// List workspace directory tree (optionally scoped to a directory)
const tree = await dench.files.list();
const subTree = await dench.files.list("documents/");

// Write a file (files:write permission)
await dench.files.write("path/to/file.md", "# Hello\n\nFile content here.");

// Delete a file (files:write permission)
await dench.files.delete("path/to/old-file.md");

// Create a directory (files:write permission)
await dench.files.mkdir("path/to/new-dir");

Waiting for Bridge Readiness

The bridge script is injected into <head>, so it's available by the time your scripts run. However, if you use defer or type="module" scripts, you can safely access window.dench immediately since module scripts run after the document is parsed.

function whenDenchReady(fn) {
  if (window.dench) return fn();
  const check = setInterval(() => {
    if (window.dench) {
      clearInterval(check);
      fn();
    }
  }, 50);
}

whenDenchReady(async () => {
  const theme = await dench.app.getTheme();
  document.body.className = theme;
});

Theme & Styling System

Apps should respect the DenchClaw theme. The bridge provides the current theme ("dark" or "light"). Build your CSS to support both.

Recommended Base Styles

* {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

body {
  font-family:
    -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
  line-height: 1.5;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  transition:
    background-color 0.2s,
    color 0.2s;
}

body.dark {
  --app-bg: #0f0f1a;
  --app-surface: #1a1a2e;
  --app-surface-hover: #252540;
  --app-border: #2a2a45;
  --app-text: #e8e8f0;
  --app-text-muted: #8888a8;
  --app-accent: #6366f1;
  --app-accent-hover: #818cf8;
  --app-success: #22c55e;
  --app-warning: #f59e0b;
  --app-error: #ef4444;
  background: var(--app-bg);
  color: var(--app-text);
}

body.light {
  --app-bg: #ffffff;
  --app-surface: #f8f9fa;
  --app-surface-hover: #f0f1f3;
  --app-border: #e2e4e8;
  --app-text: #1a1a2e;
  --app-text-muted: #6b7280;
  --app-accent: #6366f1;
  --app-accent-hover: #4f46e5;
  --app-success: #16a34a;
  --app-warning: #d97706;
  --app-error: #dc2626;
  background: var(--app-bg);
  color: var(--app-text);
}

Theme Initialization

Always apply the theme as the first action in your app:

async function initTheme() {
  try {
    const theme = await dench.app.getTheme();
    document.body.className = theme;
  } catch {
    document.body.className = "dark";
  }
}
initTheme();

Canvas-Based Apps (Games)

For p5.js, Three.js, or any canvas-based app, set the canvas background based on theme and make sure the body has no scrollbars:

body {
  margin: 0;
  padding: 0;
  overflow: hidden;
  width: 100vw;
  height: 100vh;
}

canvas {
  display: block;
}

Loading External Libraries via CDN

Since apps use runtime: "static", load libraries via CDN <script> tags. The app iframe allows external script loading.

Recommended CDNs

Use unpkg or cdnjs for reliability:

<!-- p5.js -->
<script src="https://unpkg.com/p5@1/lib/p5.min.js"></script>

<!-- Three.js -->
<script type="importmap">
  {
    "imports": {
      "three": "https://unpkg.com/three@0.170/build/three.module.js",
      "three/addons/": "https://unpkg.com/three@0.170/examples/jsm/"
    }
  }
</script>

<!-- D3.js -->
<script src="https://unpkg.com/d3@7/dist/d3.min.js"></script>

<!-- Chart.js -->
<script src="https://unpkg.com/chart.js@4/dist/chart.umd.min.js"></script>

<!-- Tone.js (audio) -->
<script src="https://unpkg.com/tone@15/build/Tone.js"></script>

<!-- Matter.js (2D physics) -->
<script src="https://unpkg.com/matter-js@0.20/build/matter.min.js"></script>

<!-- cannon-es (3D physics) -->
<script type="module">
  import * as CANNON from "https://unpkg.com/cannon-es@0.20/dist/cannon-es.js";
</script>

<!-- GSAP (animation) -->
<script src="https://unpkg.com/gsap@3/dist/gsap.min.js"></script>

<!-- Howler.js (audio) -->
<script src="https://unpkg.com/howler@2/dist/howler.min.js"></script>

Import Maps for ES Modules

For Three.js and other module-based libraries, use import maps:

<script type="importmap">
  {
    "imports": {
      "three": "https://unpkg.com/three@0.170/build/three.module.js",
      "three/addons/": "https://unpkg.com/three@0.170/examples/jsm/"
    }
  }
</script>
<script type="module" src="app.js"></script>

Multi-File App Organization

For complex apps, split code across multiple files:

apps/complex-app.dench.app/
  .dench.yaml
  index.html
  css/
    main.css
    components.css
  js/
    app.js           # Entry point
    game.js          # Game logic
    renderer.js      # Rendering
    ui.js            # UI overlays
    utils.js         # Helpers
  assets/
    sprites/
    sounds/
    models/

Using ES Modules for Multi-File JS

<script type="module" src="js/app.js"></script>

// js/app.js
import { Game } from "./game.js";
import { Renderer } from "./renderer.js";
import { UI } from "./ui.js";

const game = new Game();
const renderer = new Renderer(game);
const ui = new UI(game);

async function init() {
  if (window.dench) {
    const theme = await dench.app.getTheme();
    renderer.setTheme(theme);
  }
  game.start();
}

init();

// js/game.js
export class Game {
  constructor() {
    this.state = "menu";
    this.score = 0;
    this.entities = [];
  }

  start() {
    this.state = "playing";
    this.loop();
  }
  loop() {
    this.update();
    requestAnimationFrame(() => this.loop());
  }
  update() {
    /* game logic */
  }
}

Relative imports (./game.js) work because all files are served from the same /api/apps/serve/ base path.

Asset Management

Referencing Assets

All asset paths are relative to the .dench.app folder root:

// In p5.js
let img;
function preload() {
  img = loadImage("assets/player.png");
}

// In Three.js (module)
const texture = new THREE.TextureLoader().load("assets/texture.jpg");

// In HTML
// <img src="assets/logo.png" />
// <audio src="assets/music.mp3"></audio>

Supported MIME Types

The file server recognizes these extensions automatically:

Generating Assets Inline

For games without pre-made art, generate sprites and textures programmatically:

// p5.js: Create a sprite at runtime
function createPlayerSprite(size) {
  const g = createGraphics(size, size);
  g.noStroke();
  g.fill("#6366f1");
  g.ellipse(size / 2, size / 2, size * 0.8);
  g.fill("#818cf8");
  g.ellipse(size / 2, size / 3, size * 0.3);
  return g;
}

// Three.js: Create a texture from canvas
function createCheckerTexture(size = 256, divisions = 8) {
  const canvas = document.createElement("canvas");
  canvas.width = canvas.height = size;
  const ctx = canvas.getContext("2d");
  const cellSize = size / divisions;
  for (let y = 0; y < divisions; y++) {
    for (let x = 0; x < divisions; x++) {
      ctx.fillStyle = (x + y) % 2 === 0 ? "#ffffff" : "#cccccc";
      ctx.fillRect(x * cellSize, y * cellSize, cellSize, cellSize);
    }
  }
  const texture = new THREE.CanvasTexture(canvas);
  texture.wrapS = texture.wrapT = THREE.RepeatWrapping;
  return texture;
}

Performance & Best Practices

General

• Always use runtime: "static" unless explicitly asked for React/TSX/npm
• Request only needed permissions — no permissions needed for pure games/tools
• Keep apps self-contained — all resources within the .dench.app folder
• Use semantic HTML and responsive design
• Handle errors for all bridge API calls
• Apply the theme as the very first thing on load
• Use requestAnimationFrame for all animation loops (p5.js does this automatically)
• Clean up resources in games: remove event listeners, cancel animations, dispose Three.js objects

p5.js Performance

• Use pixelDensity(1) for pixel-art or retro-style games to avoid unnecessary high-DPI rendering
• Use noSmooth() for pixel-art aesthetics
• Minimize createGraphics() calls — create off-screen buffers once and reuse
• Object pool frequently-created entities (bullets, particles) instead of creating new objects each frame
• Use p.frameRate(60) explicitly to cap FPS
• For large worlds, only render entities visible on screen (frustum culling)
• Use p.millis() or p.deltaTime for time-based movement instead of frame-based

Three.js Performance

• Limit pixel ratio: renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))
• Reuse geometries and materials — don't create new ones per object if the shape/material is the same
• Dispose resources when no longer needed: geometry.dispose(), material.dispose(), texture.dispose()
• Use BufferGeometry (the default in modern Three.js)
• Merge static meshes with BufferGeometryUtils.mergeGeometries() for large scenes
• Use instanced rendering (InstancedMesh) for many identical objects (trees, particles)
• Limit shadow map resolution on mobile
• Use LOD (Level of Detail) for complex models: THREE.LOD
• Throttle physics to a fixed timestep (e.g., 60Hz) separate from render framerate

Memory

• For Three.js, always clean up in a dispose function:

  function dispose() {
    renderer.dispose();
    scene.traverse((obj) => {
      if (obj.geometry) obj.geometry.dispose();
      if (obj.material) {
        if (Array.isArray(obj.material)) obj.material.forEach((m) => m.dispose());
        else obj.material.dispose();
      }
    });
  }

Error Handling Patterns

Bridge API Error Handling

Always wrap bridge calls in try/catch:

async function loadData() {
  try {
    const result = await dench.db.query("SELECT * FROM objects");
    return result.rows || [];
  } catch (err) {
    console.error("Failed to load data:", err.message);
    showError("Could not load workspace data. Check permissions.");
    return [];
  }
}

Loading State Pattern

function showLoading(message = "Loading...") {
  const el = document.getElementById("loading");
  if (el) {
    el.textContent = message;
    el.style.display = "flex";
  }
}

function hideLoading() {
  const el = document.getElementById("loading");
  if (el) el.style.display = "none";
}

function showError(message) {
  const el = document.getElementById("error");
  if (el) {
    el.textContent = message;
    el.style.display = "block";
  }
}

Graceful Degradation

async function init() {
  try {
    const theme = await dench.app.getTheme();
    document.body.className = theme;
  } catch {
    document.body.className = "dark";
  }

  try {
    const data = await dench.db.query("SELECT * FROM objects");
    renderDashboard(data.rows);
  } catch {
    renderEmptyState("No data available. Make sure the app has database permission.");
  }
}

Creating an App — Step by Step Checklist

When asked to build an app, follow these steps:

1. Determine the app type — game (2D/3D), dashboard, tool, visualization, AI chat, widget, etc.
2. Choose the right library:
   • 2D game / simulation / generative art → p5.js (always) — see game-builder child skill
   • 3D game / scene / visualization → Three.js (always) — see game-builder child skill
   • Data dashboard / CRUD app → Chart.js or plain HTML/CSS — see data-builder child skill
   • AI-powered app / chat UI → use dench.chat.* API — see agent-builder child skill
   • Interactive tool / form → plain HTML/CSS/JS
3. Create the app folder: apps/<name>.dench.app/
4. Create .dench.yaml with manifest (always include name, entry, runtime, and needed permissions)
5. Create index.html as the entry point with CDN script tags
6. Create separate JS file(s) for app logic — avoid massive inline scripts
7. Apply theme via dench.app.getTheme() on init
8. Handle window resizing (canvas-based apps must call resizeCanvas / update renderer)
9. Add error handling for all bridge API calls
10. Test the app opens correctly as a tab in DenchClaw

Child Skills

This skill covers app fundamentals. For specialized APIs, see these child skills (all inside the app-builder/ skill folder):

All child skills are seeded into the workspace alongside this parent skill and can be read at {{WORKSPACE_PATH}}/skills/app-builder/<child>/SKILL.md.