starlight-protocol 1.2.1

Sovereign SDK for the Starlight Protocol

🛰️ Starlight Protocol

An Open Standard for Autonomous Browser Automation

Quick Start • Specification • Book • Roadmap

---

What is the Starlight Protocol?

The Starlight Protocol decouples intent from environment. Your test scripts describe goals; autonomous Sentinels handle the chaos.

// Traditional: Handle EVERYTHING yourself
if (await page.$('.cookie-banner')) await page.click('.dismiss');
if (await page.$('.popup')) await page.click('.close');
await page.click('#submit');

// Starlight: Express INTENT only
await hub.send({ goal: 'Submit Form' });
// Sentinels automatically clear obstacles

---

🏗️ Architecture

Component	Role
Hub	Central orchestrator, manages Playwright browser
Pulse Sentinel	Monitors DOM/Network stability
Janitor Sentinel	Clears popups, modals, banners
Vision Sentinel	AI-powered obstacle detection (Moondream)
Data Sentinel	Context extraction & injection

---

🚀 Quick Start

Prerequisites

• Node.js 18+ & Python 3.9+
• Ollama (optional, for Vision)

Install

git clone https://github.com/starlight-protocol/starlight.git
cd cba
npm install
pip install -r requirements.txt
npx playwright install chromium

Run

# One command launches everything
node bin/starlight.js test/intent_portfolio_v2.js --headless

Mission Control (GUI)

node launcher/server.js
# Open http://localhost:3000

---

🛰️ The Protocol

All communication uses JSON-RPC 2.0:

Method	Purpose
starlight.intent	Issue a goal or command
starlight.pre_check	Hub → Sentinels handshake
starlight.clear	Sentinel approves action
starlight.wait	Sentinel vetoes (retry later)
starlight.hijack	Sentinel takes browser control
starlight.resume	Sentinel releases control

📄 Full Specification

---

✨ Key Features

Feature	Description
Self-Healing Selectors	Learns alternatives when selectors fail
Animation Tolerance	Handles CSS animations without blocking
No-Code Recorder	Record tests by clicking through your site
Visual Sentinel Editor	Create custom Sentinels without code
Shadow DOM Support	Pierces web component boundaries
Webhook Alerts	Slack/Teams notifications
ROI Dashboard	Quantifies time saved

---

🛠️ Build a Sentinel

from sdk.starlight_sdk import SentinelBase

class MySentinel(SentinelBase):
    def __init__(self):
        super().__init__("MySentinel", priority=5)
        self.selectors = [".my-obstacle"]
    
    async def on_pre_check(self, params, msg_id):
        # Your detection logic
        await self.send_clear()

if __name__ == "__main__":
    import asyncio
    asyncio.run(MySentinel().start())

---

📚 Documentation

Document	Description
📖 Book	Comprehensive guide
📄 Specification	Formal protocol standard
📋 User Guide	Getting started
⚙️ Technical Guide	SDK & configuration
🗺️ Roadmap	Future plans
📝 Changelog	Version history

---

🐳 Docker

docker-compose up --build

---

📖 Blog Series

• Part 1: The Inner Workings
• Part 2: Mission Control & ROI
• Part 3: The Autonomous Era

---

📄 License

MIT License - LICENSE

---

"Don't look at the ground; look at the Starlight."

Built with ❤️ by Dhiraj Das