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

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"]

// 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"

// 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");

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;
});

* { 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);
}

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

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

canvas {
  display: block;
}

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

<!-- Three.js -->
<script type="importmap">
{
  "imports": {
    "three": "https://unpkg.com/[email protected]/build/three.module.js",
    "three/addons/": "https://unpkg.com/[email protected]/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/[email protected]/build/matter.min.js"></script>

<!-- cannon-es (3D physics) -->
<script type="module">
import * as CANNON from 'https://unpkg.com/[email protected]/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>

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

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/

<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 */ }
}

// 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>

// 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;
}

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 [];
  }
}

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'; }
}

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.');
  }
}