Contributing Guide - Time Capsule

Development Setup

Prerequisites

Before starting development, ensure you have the following installed:

Node.js v20+ - JavaScript runtime
npm v10+ - Package manager

Quick Start

Get the project running locally in three simple steps:

git clone <your-fork>
npm install
npm run dev

The development server will start at http://localhost:4321.

The project uses Astro with TypeScript. The dev server provides hot module replacement for fast development.

Pull Request Process

Before Submitting

Run these checks before creating a pull request:

Format Code

Run the formatter to ensure consistent code style:

npm run format

Build Verification

Verify the build completes successfully:

npm run build

This must pass without errors.

Test Functionality

Manually test your changes across different screen sizes:

Desktop: Window management, drag & drop, right-click menus
Mobile: Touch gestures, responsive layouts

Lint Check

Follow existing TypeScript patterns and strict typing requirements.

PR Requirements

Documentation

Reference issue number if applicableInclude clear description of changes

Testing

Test on desktop and mobile for UI changesVerify theme system if modifying styles

Code Quality

Follow existing code patternsMaintain architecture consistency

Build Status

Ensure build passesFix any TypeScript errors

Review Process

Automatic Deployment: PRs merged to main deploy automatically
Build Verification: GitHub Actions validates builds
Manual Testing: UI/UX changes undergo manual review

Code Standards

TypeScript

The project uses strict TypeScript configuration:

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

Strict Typing

All variables must have explicit types
No any types unless absolutely necessary
Use existing interfaces and types from core systems

Code Patterns

Follow patterns in /src/scripts/
Use class-based architecture for core systems
Implement proper error handling

Import Standards

Use relative imports for local modules
Import from utilities for shared functionality
Lazy load features when possible

CSS

Variables
Naming
Responsive

Use existing CSS variables from /public/css/base/variables.css:

.my-component {
  background: var(--cde-bg-primary);
  color: var(--cde-text-primary);
  border: 1px solid var(--cde-border-color);
}

Follow BEM-like naming conventions:

.component-name { }
.component-name__element { }
.component-name--modifier { }

Maintain responsive design principles:

@media (max-width: 768px) {
  .component {
    flex-direction: column;
  }
}

File Organization

The codebase follows a modular structure:

src/
├── components/          # Astro UI components
│   ├── common/         # Shared components
│   ├── desktop/        # Desktop-specific components
│   └── features/       # Feature islands
├── scripts/
│   ├── core/           # Core systems (VFS, WindowManager)
│   ├── features/       # Business logic for features
│   ├── utilities/      # Helper functions
│   ├── shared/         # Shared functionality
│   ├── ui/             # UI utilities
│   └── workers/        # Web Workers
└── data/               # Static data files

Do not modify core system files without understanding the architecture. See Architecture Overview for details.

Architecture Guidelines

Key Systems

Refer to technical documentation for detailed architecture:

Architecture

System design and module patterns

Storage

IndexedDB and localStorage usage

Version Updates

Update system and migrations

Module Patterns

Style modules must implement these methods:

class MyStyleModule {
  // Load settings from storage
  async load(): Promise<void> {
    const settings = await settingsManager.getSection('mymodule');
    this.applySettings(settings);
  }

  // Apply changes to the UI
  apply(settings: MySettings): void {
    // Update CSS variables or DOM
  }

  // Sync UI controls with current state
  syncUI(): void {
    // Update checkboxes, sliders, etc.
  }

  // Handle setting changes
  update(key: string, value: any): void {
    settingsManager.setSection('mymodule', { [key]: value });
    this.apply({ [key]: value });
  }
}

See existing style modules in /src/scripts/features/style/ for reference implementations.

Performance Considerations

Web Workers

Use Web Workers for heavy operations:

// Example: XPM parser (xpmparser.ts)
const worker = new Worker('/workers/xpm-worker.js');
worker.postMessage({ type: 'parse', data: xpmData });
worker.onmessage = (e) => {
  // Handle result
};

Lifecycle Management

Implement proper cleanup:

class MyFeature {
  private listeners: Function[] = [];

  init(): void {
    const handler = () => { /* ... */ };
    window.addEventListener('resize', handler);
    this.listeners.push(() => {
      window.removeEventListener('resize', handler);
    });
  }

  destroy(): void {
    this.listeners.forEach(cleanup => cleanup());
  }
}

Caching

Cache expensive operations:

class ThemeManager {
  private cache = new Map<string, string>();

  getProcessedTheme(id: string): string {
    if (this.cache.has(id)) {
      return this.cache.get(id)!;
    }
    const result = this.processTheme(id);
    this.cache.set(id, result);
    return result;
  }
}

Common Tasks

Adding a New Style Module

Create Module File

Create your module in /src/scripts/features/style/:

// my-style-module.ts
export class MyStyleModule {
  async load() { /* ... */ }
  apply(settings) { /* ... */ }
  syncUI() { /* ... */ }
  update(key, value) { /* ... */ }
}

Add to StyleManager constructor:

// style-manager.ts
import { MyStyleModule } from './my-style-module';

constructor() {
  this.modules.set('mymodule', new MyStyleModule());
}

Add UI Component

Create component in /src/components/features/style/:

---
// MyStyleControls.astro
---
<div class="style-control">
  <label>My Setting</label>
  <input type="checkbox" id="my-setting" />
</div>

Add CSS Styles

Add styles in /public/css/components/style-manager/:

.style-control {
  padding: 10px;
  border-bottom: 1px solid var(--cde-border-color);
}

Adding a Desktop Icon

Add Icon File

Place icon in /public/icons/ (preferably SVG or PNG).

Update SYSTEM_ICONS

Edit desktop.ts:

const SYSTEM_ICONS = [
  // ... existing icons
  {
    id: 'my-app',
    label: 'My App',
    icon: '/icons/my-app.svg',
    action: 'launch-my-app'
  }
];

Implement Click Handler

Add handler if needed:

if (action === 'launch-my-app') {
  const myApp = await lazyLoader.load('myapp');
  myApp.launch();
}

Modifying Themes

XPM backdrops use palette colors. Clear cache on palette changes to ensure proper rendering.

Test with Multiple Palettes

Ensure your theme works with different color palettes from /src/data/cde_palettes.json.

Handle Backdrop Rendering

XPM files are parsed with current palette colors:

// When palette changes
themeManager.clearBackdropCache();
themeManager.reapplyBackdrop();

Test URL Sharing

Verify theme state is preserved in URL parameters for sharing.

Testing

Manual Testing Checklist

Desktop Functionality

Window management (open, close, minimize, maximize)
Drag and drop operations
Right-click context menus
Keyboard shortcuts
Multi-window interactions

Mobile Functionality

Touch gestures (tap, swipe, pinch)
Responsive layouts
Mobile menu navigation
Virtual keyboard handling

Theme System

Palette changes apply correctly
Backdrop rendering works
Theme state persists
URL sharing preserves theme
Cache clears on palette change

Build Verification

Run these commands to verify your changes:

# Format code
npm run format

# Build project (must pass)
npm run build

# Preview production build
npm run preview

The build process uses Astro for static site generation and Vite for bundling. TypeScript compilation happens during build.

Documentation

For detailed information about the system architecture and features:

User Guide

End-user documentation and tutorials

Technical Docs

System architecture and implementation

Documentation Standards

Language
Formatting
Visuals
Completeness

Use clear, concise English
Avoid unnecessary jargon
Define technical terms when first used
Write for both beginners and experts

Contributing to Documentation

Found an error or want to improve the documentation?

Identify

Find the relevant .md file in the docs/ directory.

Edit

Make your changes, ensuring they follow the standards above.

Verify

Check that all links work and formatting is correct.

Submit PR

Submit a pull request with a description of the documentation improvements.

For major documentation changes, please open an issue first to discuss the structure.

Issues and Discussions

Bug Reports

Use GitHub Issues with:

Clear reproduction steps
Expected vs actual behavior
Environment details
Screenshots if applicable

Feature Requests

Propose in GitHub Discussions:

Describe the use case
Explain expected behavior
Consider implementation impact

Questions

Before asking:

Check existing documentation
Search closed issues
Review architecture docs

Build Information

Built with TypeScript, Astro, and authentic CDE design principles. Current version: 1.0.31

Project Dependencies

{
  "dependencies": {
    "astro": "^5.18.0",
    "marked": "^17.0.3"
  },
  "devDependencies": {
    "prettier": "^3.8.1",
    "prettier-plugin-astro": "^0.14.1"
  }
}

Available Scripts

Script	Command	Description
Dev	`npm run dev`	Start development server
Build	`npm run build`	Build for production
Preview	`npm run preview`	Preview production build
Format	`npm run format`	Format code with Prettier

Architecture

Development

​Development Setup

​Prerequisites

​Quick Start

​Pull Request Process

​Before Submitting

​PR Requirements

Documentation

Testing

Code Quality

Build Status

​Review Process

​Code Standards

​TypeScript

​CSS

​File Organization

​Architecture Guidelines

​Key Systems

Architecture

Storage

Version Updates

​Module Patterns

​Performance Considerations

​Common Tasks

​Adding a New Style Module

​Adding a Desktop Icon

​Modifying Themes

​Testing

​Manual Testing Checklist

​Build Verification

​Documentation

User Guide

Technical Docs

​Documentation Standards

​Contributing to Documentation

​Issues and Discussions

Bug Reports

Feature Requests

Questions

​Build Information

​Project Dependencies

​Available Scripts

Development Setup

Prerequisites

Quick Start

Pull Request Process

Before Submitting

PR Requirements

Review Process

Code Standards

TypeScript

CSS

File Organization

Architecture Guidelines

Key Systems

Module Patterns

Performance Considerations

Common Tasks

Adding a New Style Module

Adding a Desktop Icon

Modifying Themes

Testing

Manual Testing Checklist

Build Verification

Documentation

Documentation Standards

Contributing to Documentation

Issues and Discussions

Build Information

Project Dependencies

Available Scripts