# cicada

**Repository Path**: MultiDev/cicada

## Basic Information

- **Project Name**: cicada
- **Description**: cicada
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-04-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cicada

A lightweight, embeddable web kernel for Android written in pure Kotlin. Cicada renders HTML/CSS content to native Android Views without depending on WebView or Chromium.

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Application Layer                     │
│                   (app module - demo)                    │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐  │
│  │   Cicada     │  │  CicadaView  │  │ CaptureBitmap │  │
│  │ (Parse/Style)│──│  (Render)   │──│    View       │  │
│  │              │  │              │  │  (Export)     │  │
│  └──────────────┘  └──────────────┘  └───────────────┘  │
│         │                  │                 │           │
│         ▼                  ▼                 ▼           │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐  │
│  │    Ksoup     │  │  Native View │  │  Bitmap/PDF   │  │
│  │  (HTML DOM)  │  │  Hierarchy   │  │   Export      │  │
│  │  Simple CSS  │  │              │  │               │  │
│  └──────────────┘  └──────────────┘  └───────────────┘  │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

### Core Components

| Component | File | Responsibility |
|-----------|------|----------------|
| `Cicada` | `Cicada.kt` | HTML fetching, CSS parsing, document model, navigation history |
| `CicadaView` | `CicadaView.kt` | Renders parsed document to Android View hierarchy |
| `CaptureBitmapView` | `CaptureBitmapView.kt` | Captures rendered views to Bitmap, PNG, JPEG, WebP, PDF |
| `CicadaDocument` | `Cicada.kt` | Wraps Ksoup Document with CSS-aware element queries |
| `CicadaNode` | `Cicada.kt` | Represents a styled HTML element with computed CSS properties |
| `CicadaEvent` | `Cicada.kt` | Event types emitted by Cicada core |
| `CicadaViewEvent` | `CicadaView.kt` | Event types emitted by CicadaView renderer |

## Features

- **Zero WebView dependency** — renders to native Android Views (LinearLayout, TextView, ImageView, etc.)
- **Jsoup HTML parsing** — Java HTML parser with CSS selector support
- **Custom CSS parser** — lightweight CSS parsing and selector matching
- **CSS shorthand expansion** — handles margin, padding, border, font, background, flex shorthands
- **Navigation history** — back/forward navigation with page caching
- **Event-driven architecture** — dual-bind event system between Cicada core and CicadaView
- **Element queries** — CSS selector queries (`querySelector`, `querySelectorAll`, `$()`)
- **Image loading** — async image fetching with memory cache
- **View capture** — render to Bitmap, save to PNG/JPEG/WebP/PDF
- **Form elements** — inputs, buttons, textareas, checkboxes, radio buttons, selects
- **Table rendering** — basic table layout with border-collapse support
- **Viewport meta** — respects `<meta name="viewport">` width/height

### HTML5 Elements Support (70+)

- **Block elements**: div, p, h1-h6, section, article, main, header, footer, nav, aside
- **Lists**: ul, ol, li, dl, dt, dd
- **Tables**: table, thead, tbody, tfoot, tr, th, td, caption
- **Forms**: form, fieldset, legend, input, button, textarea, select
- **Media**: img, picture, source, video, audio, canvas
- **HTML5**: details, summary, figure, figcaption, dialog, progress, meter
- **Semantic**: ruby, rt, rp, address, output
- **Text**: span, a, strong, b, em, i, u, small, mark, time, data, dfn, abbr, cite, q, s, del, ins, sub, sup, code, var, samp, kbd

## Dependencies

| Library | Version | Purpose |
|---------|---------|---------|
| [Jsoup](https://github.com/jhy/jsoup) | 1.17.2 | Java HTML parser - CSS selector, DOM traversal |
| [Kotlin Coroutines](https://github.com/Kotlin/kotlinx.coroutines) | 1.7.3 | Async operations (fetching, image loading) |
| [AndroidX Core KTX](https://developer.android.com/jetpack/androidx/releases/core) | 1.3.2 | Kotlin extensions for Android framework |
| [AndroidX Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) | 2.6.2 | Lifecycle-aware components |

## Requirements

- **Min SDK**: 14 (Android 4.0)
- **Compile SDK**: 35
- **JVM Target**: 17
- **Kotlin**: 2.3.0

## Project Structure

```
cicada/
├── app/                          # Demo application
│   └── src/main/
│       ├── java/rj/cicadademo/
│       │   └── MainActivity.kt   # Demo activity
│       └── res/layout/
│           └── activity_main.xml  # Demo layout
│
├── cicada/                       # Library module
│   └── src/main/java/rj/cicada/
│       ├── Cicada.kt             # Core engine
│       ├── CicadaView.kt         # View renderer
│       └── CaptureBitmapView.kt  # Screenshot/PDF export
│
├── build.gradle.kts              # Root build config
├── settings.gradle.kts           # Module configuration
└── gradle.properties             # Gradle settings
```

## Integration

Add to your project:

```kotlin
// settings.gradle.kts
include(":cicada")

// app/build.gradle.kts
dependencies {
    implementation(project(":cicada"))
}
```

See [USAGE.md](USAGE.md) for detailed API documentation and examples.

## Limitations

- **No JavaScript engine** — pure HTML/CSS rendering only
- **Limited CSS support** — no animations, transitions, or complex selectors (pseudo-classes, combinators)
- **Simplified layout** — uses LinearLayout instead of full CSS box model; no float, absolute positioning, or grid
- **No media playback** — video/audio elements render as placeholders
- **No form submission** — forms render but do not submit to servers
- **No cookie/session management**
- **Limited SVG support**

## License

See LICENSE file for details.