@patchedcodes/hackathon-widget

AI-powered frontend editor widget — modify live web interfaces using natural language.

Renders a floating chat button on your page. Users type a natural-language command, the widget captures a screenshot, sends it to your backend, and applies the resulting code changes live.

Install

npm install @patchedcodes/hackathon-widget

or

pnpm add @patchedcodes/hackathon-widget

Quick Start

import { init } from "@patchedcodes/hackathon-widget";

init({
  endpoint: "https://your-backend.com/api/command",
  apiKey: "your-api-key",
});

A floating button appears in the bottom-right corner of your page. Click it to open the chat panel, describe a visual change, and the widget handles the rest.

Configuration

init() accepts a WidgetConfig object:

Option	Type	Default	Description
endpoint	string	(required)	Backend URL that receives command POST requests.
apiKey	string	(required)	API key sent in the request body to authenticate with the backend.
position	"bottom-right" | "bottom-left" | "top-right" | "top-left"	"bottom-right"	Position of the floating widget button.
theme	"light" | "dark"	"light"	Widget color theme.
headers	Record<string, string>	{}	Custom headers sent with backend requests (e.g. auth tokens).
onDeployReady	(branch: string, previewUrl: string) => void	—	Called when a deployment is ready, before the user clicks "Apply".
onError	(error: Error) => void	—	Called when an error occurs.
onOpen	() => void	—	Called when the widget panel is opened.
onClose	() => void	—	Called when the widget panel is closed.

Callbacks

init({
  endpoint: "https://your-backend.com/api/command",
  apiKey: "your-api-key",
  onDeployReady: (branch, previewUrl) => {
    console.log(`Deploy ready on branch ${branch}: ${previewUrl}`);
  },
  onError: (error) => {
    console.error("Widget error:", error);
  },
  onOpen: () => console.log("Widget opened"),
  onClose: () => console.log("Widget closed"),
});

Programmatic Control

init() returns the underlying DevloyedWidget custom element, which exposes methods for programmatic control:

const widget = init({
  endpoint: "https://your-backend.com/api/command",
  apiKey: "your-api-key",
});

// Open, close, or toggle the chat panel
widget.open();
widget.close();
widget.toggle();

Architecture

The widget is a vanilla TypeScript Web Component (<devloyed-widget>) that renders inside a Shadow DOM. This means:

• Full style encapsulation — widget styles cannot leak into or be affected by the host page.
• Framework-agnostic — works with React, Vue, Svelte, plain HTML, or any other framework.
• Single bundle — ships as one ES module (dist/devloyed-widget.js) with no external runtime dependencies beyond html2canvas (bundled).

How It Works

1. User opens the widget and types a natural-language command (e.g. "Make the header blue").
2. The widget captures a screenshot of the page using html2canvas.
3. A multi-step loader plays with randomized progress labels while the request is in flight.
4. The command and API key are sent to your backend via a single POST request.
5. On response, the loader cascades to completion and the AI's response is shown in the chat.
6. If the backend returns a commitId, a deploy toast appears with an "Apply" button that reloads the page to pick up the changes.

Backend Contract

The widget sends a POST request to your endpoint with the following JSON body:

interface CommandRequest {
  apiKey: string;   // The API key from config
  prompt: string;   // The user's natural-language command
}

Your backend should return:

interface CommandResponse {
  commitId: string;    // The commit SHA that was pushed
  transcript: string;  // AI's explanation of what was changed
}

Routing Utilities

The package exports cookie-based routing helpers for reverse-proxy branch switching. These are standalone utilities — not wired into the widget automatically — for consumers who want to implement branch preview routing.

import {
  setRoutingCookie,
  getRoutingCookie,
  clearRoutingCookie,
  isOnPreview,
} from "@patchedcodes/hackathon-widget";

// Set cookie to route traffic to a preview branch (reloads by default)
setRoutingCookie("feature/new-header");

// Check current branch
const branch = getRoutingCookie(); // "feature/new-header" or null

// Check if viewing a preview
if (isOnPreview()) {
  // show "return to production" button
}

// Clear and return to production
clearRoutingCookie();

Options can be passed to setRoutingCookie and clearRoutingCookie:

Option	Type	Default	Description
cookieName	string	"devloyed_branch"	Cookie name.
maxAge	number	3600	Cookie max-age in seconds.
path	string	"/"	Cookie path.
reload	boolean	true	Whether to reload the page after setting/clearing.

Development

# Start dev server with mock backend
npm run dev

# Or run them separately:
npm run dev:mock   # Mock backend on port 3001
npm run dev:vite   # Vite dev server

# Type-check
npm run typecheck

# Build
npm run build

The mock server (dev/mock-server.mjs) simulates a ~10-second AI processing delay and returns fake commit/branch data for any command.

TypeScript

Types are shipped with the package — no separate @types/ install needed. You can import them directly:

import type { WidgetConfig } from "@patchedcodes/hackathon-widget";
import type { CommandRequest, CommandResponse } from "@patchedcodes/hackathon-widget";

The package also exports DevloyedWidget and TransportClient classes for advanced usage.

License

MIT