lively4-core

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

AI Collaboration Experiment

A significant part of this AI collaboration is an experiment to teach Claude Code how to develop in Lively4. By working together on real development tasks, we are:

This documentation serves dual purposes: guiding AI development work and creating human-readable documentation of Lively4’s development practices. The demos/claude/ directory contains examples and experiments from this collaborative learning process.

Essential Commands

Testing:

Example:

npm run test-single test/client/strings-test.js
# ✅ 6 tests passed, 0 failed in 0.01s

Development:

In-Browser Development:

Core Architecture

Lively4 System: Self-supporting browser-based development environment using:

Module System:

Central API (src/client/lively.js):

Special URL Schemes (via fetch() with eval):

Server Integration:

File Organization & Patterns

Directory Structure:

Component Development Pattern:

  1. Create paired files: templates/my-component.html + templates/my-component.js
  2. Components extend Morph and follow this structure:
export default class MyComponent extends Morph {
  async initialize() {
    this.windowTitle = "Component Title";
    this.registerButtons(); // auto-registers onButtonName handlers
    lively.html.registerKeys(this); // auto-registers onKeyDown handlers
    
    // IMPORTANT: Preserve existing state during live updates
    // Use || operator to keep existing data during livelyMigrate
    this._cachedData = this._cachedData || [];
    this._processedResults = this._processedResults || new Map();
    // Always reset volatile state:
    this._currentOperation = null;
    
    // IMPORTANT: Don't block in initialize() with async operations
    // Use non-blocking calls for data loading:
    this.loadData(); // NOT: await this.loadData()
  }
  
  async loadData() {
    // Heavy async operations should be separate from initialize()
    // This allows the component to render immediately
  }
  
  livelyExample() {
    // Customize instance with example content
  }
  
  livelyMigrate(other) {
    // Handle live updates during development
    this.someProperty = other.someProperty;
  }
}

Template Pattern (HTML):

<template id="my-component">
  <style data-src="/templates/livelystyle.css"></style>
  <style>/* component-specific styles */</style>
  <div id="content">
    <button id="myButton">Click Me</button>
  </div>
</template>

Key Integration Points

Container System: lively-container (src/components/tools/lively-container.js)

Event System: Use lively.addEventListener() for proper cleanup:

lively.addEventListener("myId", this, "click", evt => this.onClick(evt))
// Automatically cleaned up with lively.removeEventListener("myId", this)

Component Access:

this.get("#selector") // querySelector in component and shadowRoot
await lively.openComponentInWindow("component-name")

Development Guidelines

Naming Conventions:

Event Handler Registration:

// Automatic button registration
this.registerButtons(); // Finds buttons by ID and registers on[ButtonName] handlers

// Manual event registration with cleanup
lively.addEventListener("myId", this, "click", evt => this.onClick(evt))

Interactive Markdown Development

Script Integration in Markdown Files:

Development Journal

Journal Entry Format:

## YYYY-MM-DD General Day Title #hashtags #topics #keywords
*Author: @JensLincke [with @BlindGoldie]*

Brief technical description of what was implemented/changed.

- **Added**: [file.js](edit://path/to/file.js), [file.html](edit://path/to/file.html)
- **Modified**: [existing-file.js](edit://path/to/file.js) - description of changes
- **Feature**: Technical details with method names and implementation specifics
- **UI**: Interface changes and user-facing features

**Technical details:**
- Specific implementation notes
- Method signatures or key code patterns
- Integration points

**TODO**: 
- [ ] #TODO Future improvements needed

MCP Integration

Model Context Protocol (MCP) enables Claude Code to interact directly with live Lively4 environments:

Architecture:

Available Tools:

Adding New Tools:

  1. Define tool in ../lively4-server/tools.json with description, inputSchema, and endpoint
  2. Implement handler method in mcp-server.js following existing patterns
  3. Tools automatically registered on server startup

Usage:

// Open MCP component in browser
lively.openComponentInWindow('lively-mcp')

// Claude Code can then execute code in the live environment

TODO:

Special Notes

This site is open source. Improve this page.