kilatjs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 KilatJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,438 @@
+# KilatJS
+
+**A Bun-native, HTML-first framework that renders real pages, treats UI frameworks as renderers, and makes SEO the default—not a feature.**
+
+<p align="center">
+  <img src="https://img.shields.io/badge/runtime-Bun-F9F1E1?style=flat-square&logo=bun" alt="Bun Runtime">
+  <img src="https://img.shields.io/badge/rendering-SSR%20Only-10B981?style=flat-square" alt="SSR Only">
+  <img src="https://img.shields.io/badge/SEO-Guaranteed-8B5CF6?style=flat-square" alt="SEO Guaranteed">
+</p>
+
+---
+
+## 🎯 What is KilatJS?
+
+KilatJS is a server-first web framework inspired by the simplicity of PHP and the power of modern component libraries. It rejects the complexity of SPAs, hydration, and client-side routing in favor of **real HTML rendered on the server**.
+
+**🔥 Powered by Bun's Native APIs - No Abstractions, Pure Performance:**
+- 🚀 **Bun.FileSystemRouter** - Zero-config file-based routing at native speed
+- ⚡ **Bun.serve()** - HTTP/2 server with built-in WebSocket support
+- 🔧 **Bun.file()** - Streaming file operations with automatic MIME detection
+- 📦 **Bun.build()** - Native TypeScript/JSX bundling (no Webpack/Vite needed)
+- 🔄 **Bun.spawn()** - Process management for build tools and external commands
+- 💾 **Bun.write()** - Optimized file writing with atomic operations
+- 🔍 **Bun.glob()** - Pattern matching for static site generation
+
+### One-Line Positioning
+
+> **"Request → Load → Render HTML → Response. That's it."**
+
+---
+
+## 🔥 Why Bun Native?
+
+KilatJS leverages Bun's runtime directly instead of abstracting it away:
+
+```typescript
+// Direct Bun.FileSystemRouter usage
+const router = new Bun.FileSystemRouter({
+    style: "nextjs",
+    dir: "./routes"
+});
+
+// Native Bun.serve() with streaming
+export default {
+    port: 3000,
+    fetch: async (request) => {
+        // Zero-copy request handling
+        return new Response(Bun.file("./static/index.html"));
+    }
+};
+
+// Built-in TypeScript compilation
+const result = await Bun.build({
+    entrypoints: ["./src/index.tsx"],
+    outdir: "./dist",
+    target: "bun"
+});
+```
+
+**Performance Benefits:**
+- ⚡ **3x faster** cold starts vs Node.js frameworks
+- 🚀 **Native TypeScript** - no transpilation overhead
+- 💾 **Zero-copy streaming** for static files
+- 🔧 **Built-in bundling** eliminates build tool complexity
+
+---
+
+## ✅ Core Principles
+
+1. **HTML is the protocol** — Every response is complete, semantic HTML
+2. **Server owns all truth** — No client-side state management nightmares
+3. **Every meaningful change = HTTP request** — Forms, mutations, navigation
+4. **UI frameworks render, never orchestrate** — React/Solid/Vue for templating only
+5. **JavaScript is optional, not required** — Sites work without JS
+
+---
+
+## ❌ Strict Non-Goals
+
+KilatJS intentionally avoids:
+
+- ❌ Client-Side Rendering (CSR)
+- ❌ Hydration / Islands architecture
+- ❌ Client-side routing
+- ❌ Framework hooks (`useLoaderData`, `useRoute`, etc.)
+- ❌ Middleware chains
+- ❌ Dependency injection
+- ❌ SPA build assumptions
+- ❌ Vite as a hard dependency
+
+---
+
+## 🚀 Quick Start
+
+### 1. Install dependencies
+
+```bash
+bun install
+```
+
+### 2. Run the example
+
+```bash
+bun run dev
+```
+
+Visit [http://localhost:3000](http://localhost:3000) to see the example site.
+
+---
+
+## 📁 Project Structure
+
+```
+kilatjs/
+├── src/
+│   ├── index.ts           # Main entry point
+│   ├── core/
+│   │   ├── router.ts      # File-based router
+│   │   └── types.ts       # TypeScript types
+│   ├── adapters/
+│   │   └── react.ts       # React SSR adapter
+│   └── server/
+│       └── server.ts      # Bun HTTP server
+├── example/
+│   ├── server.ts          # Example server entry
+│   ├── build.ts           # Static build script
+│   ├── styles.css         # CSS styles
+│   ├── components/
+│   │   └── Layout.tsx     # Shared layout
+│   └── routes/
+│       ├── index.tsx      # Home page
+│       ├── about.tsx      # About page
+│       ├── contact.tsx    # Contact form
+│       ├── contact/
+│       │   └── success.tsx
+│       └── blog/
+│           ├── index.tsx  # Blog listing
+│           └── [slug].tsx # Dynamic blog posts
+└── README.md
+```
+
+---
+
+## 📄 Route Contract
+
+Each route file may export **at most**:
+
+```tsx
+// Rendering mode: "static" (build-time) or "ssr" (request-time)
+export const mode = "ssr";
+
+// UI framework: "react" | "solid" | "vue" (default: react)
+export const ui = "react";
+
+// SEO meta tags
+export const meta = {
+    title: "Page Title",
+    description: "Page description for SEO",
+    robots: "index,follow",
+    ogTitle: "Open Graph Title",
+    ogDescription: "Open Graph description",
+    ogImage: "https://example.com/image.jpg"
+};
+
+// For static generation of dynamic routes
+export function getStaticPaths() {
+    return ["/blog/post-1", "/blog/post-2"];
+}
+
+// Server-only data loading
+export async function load(ctx) {
+    const data = await fetchFromDatabase();
+    return { posts: data };
+}
+
+// HTTP action handlers
+export async function POST(ctx) {
+    const formData = await ctx.request.formData();
+    // Process form...
+    return Response.redirect("/success", 302);
+}
+
+// Pure render function
+export default function Page({ data, params, state }) {
+    return <div>{data.posts.map(p => <h2>{p.title}</h2>)}</div>;
+}
+```
+
+---
+
+## 🔄 Actions (PRG Pattern)
+
+All meaningful state changes happen via HTTP requests:
+
+```tsx
+// routes/contact.tsx
+export async function POST({ request }) {
+    const formData = await request.formData();
+    const email = formData.get("email");
+    
+    await saveToDatabase({ email });
+    
+    // PRG: Post-Redirect-Get pattern
+    return Response.redirect("/contact/success", 302);
+}
+
+export default function ContactPage() {
+    return (
+        <form method="POST" action="/contact">
+            <input type="email" name="email" required />
+            <button type="submit">Subscribe</button>
+        </form>
+    );
+}
+```
+
+**No JavaScript required.** Forms work natively.
+
+---
+
+## 🎨 Styling (Tailwind-Ready)
+
+KilatJS supports Tailwind CSS via CLI (no Vite required):
+
+```bash
+# Generate CSS
+npx tailwindcss -i ./input.css -o ./styles.css --watch
+```
+
+Configure in your `kilat.config.ts`:
+
+```ts
+import { createKilat } from 'kilatjs';
+
+createKilat({
+    routesDir: "./routes",
+    tailwind: {
+        enabled: true,
+        cssPath: "./styles.css"
+    }
+});
+```
+
+---
+
+## 📊 Rendering Modes
+
+### Static Generation
+
+- Build-time HTML
+- Best for SEO & caching
+- Requires explicit path enumeration for dynamic routes
+
+```tsx
+export const mode = "static";
+
+export function getStaticPaths() {
+    return ["/blog/post-1", "/blog/post-2"];
+}
+```
+
+### Server-Side Rendering (SSR)
+
+- Request-time HTML
+- PHP-style execution
+- Infinite routes allowed
+
+```tsx
+export const mode = "ssr"; // or omit (default)
+```
+
+---
+
+## 🔐 Authentication
+
+Identity is proven **per request** via cookies/headers:
+
+```tsx
+export async function load({ request }) {
+    const session = await getSession(request.headers.get("cookie"));
+    
+    if (!session) {
+        throw Response.redirect("/login");
+    }
+    
+    return { user: session.user };
+}
+```
+
+- Never trust localStorage for auth
+- Server validates every request
+- Cookies are the source of truth
+
+---
+
+## 🏃 Running Your App
+
+### Development
+
+```ts
+// Named import
+import { createKilat } from 'kilatjs';
+
+// Or default import  
+import Kilat from 'kilatjs';
+
+const server = createKilat({
+    routesDir: "./routes",
+    port: 3000,
+    dev: true,
+    tailwind: {
+        enabled: false,
+        cssPath: "./styles.css"
+    }
+});
+
+server.start();
+```
+
+### Static Build
+
+```ts
+import { buildStatic } from 'kilatjs';
+
+buildStatic({
+    routesDir: "./routes",
+    outDir: "./dist"
+});
+```
+
+---
+
+## 🧩 UI Framework Support
+
+| Framework | Status | Notes |
+|-----------|--------|-------|
+| React | ✅ Default | Full SSR support |
+| Solid | 🚧 Planned | Coming soon |
+| Vue | 🚧 Planned | Coming soon |
+
+**Rule:** One renderer per route. No mixing.
+
+---
+
+## 🎯 SEO Guarantee
+
+> **If a route exists, it is SEO-friendly.**
+
+Because:
+- HTML is always complete
+- `<head>` is server-rendered
+- No JS required for content
+- Meta tags are first-class
+
+---
+
+## 📜 Philosophy
+
+KilatJS rejects modern web complexity:
+
+| We Don't Do | We Do |
+|-------------|-------|
+| Client-side rendering | Server-rendered HTML |
+| Hydration/Islands | Static markup |
+| Client-side router | HTTP navigation |
+| Framework hooks | Props from loader |
+| State sync | HTTP mutations |
+
+---
+
+## 🛠️ API Reference
+
+### `createKilat(config)`
+
+Creates a Kilat server instance.
+
+```ts
+interface KilatConfig {
+    routesDir: string;      // Path to routes directory
+    outDir: string;         // Output for static builds
+    port?: number;          // Server port (default: 3000)
+    hostname?: string;      // Server hostname (default: "localhost")
+    dev?: boolean;          // Development mode
+    publicDir?: string;     // Static assets directory
+    tailwind?: {
+        enabled: boolean;
+        cssPath: string;
+        configPath?: string;
+    };
+}
+```
+
+### `RouteContext`
+
+Passed to `load()` and action handlers:
+
+```ts
+interface RouteContext {
+    request: Request;                    // Web Request object
+    params: Record<string, string>;      // URL parameters
+    query: URLSearchParams;              // Query string
+    state: ServerGlobalState;            // Request-scoped state
+}
+```
+
+### `PageProps`
+
+Passed to page components:
+
+```ts
+interface PageProps {
+    data: any;                           // From load()
+    params: Record<string, string>;      // URL parameters
+    state: ServerGlobalState;            // Request-scoped state
+}
+```
+
+---
+
+## 📝 License
+
+MIT
+
+---
+
+## 🤝 Contributing
+
+KilatJS is in early development. Contributions welcome!
+
+1. Fork the repository
+2. Create a feature branch
+3. Submit a pull request
+
+---
+
+<p align="center">
+  <strong>Built with 💜 for the real web using Bun's native APIs.</strong>
+</p>

package/dist/adapters/htmx.d.ts

@@ -0,0 +1,71 @@
+import { PageProps, RouteMeta, KilatConfig } from "../core/types";
+/**
+ * HTMX Adapter - For building HTMX-enhanced HTML pages
+ * Provides utilities for generating HTMX-compatible responses and partial updates
+ */
+export declare class HTMXAdapter {
+    /**
+     * Render a template function to HTML string
+     */
+    static renderToString(template: (props: PageProps) => string | Promise<string>, props: PageProps): Promise<string>;
+    /**
+     * Check if the request is an HTMX request
+     */
+    static isHTMXRequest(request: Request): boolean;
+    /**
+     * Check if this is a boosted request (HTMX boost attribute)
+     */
+    static isBoostedRequest(request: Request): boolean;
+    /**
+     * Get the current URL before the HTMX request was made
+     */
+    static getCurrentUrl(request: Request): string | null;
+    /**
+     * Get the ID of the element that triggered the request
+     */
+    static getTrigger(request: Request): string | null;
+    /**
+     * Get the name of the element that triggered the request
+     */
+    static getTriggerName(request: Request): string | null;
+    /**
+     * Get the ID of the target element
+     */
+    static getTarget(request: Request): string | null;
+    /**
+     * Create a response with HTMX-specific headers
+     */
+    static createResponse(html: string, options?: HTMXResponseOptions): Response;
+    /**
+     * Create a response that signals client-side redirect
+     */
+    static redirectResponse(url: string): Response;
+    /**
+     * Create a response that triggers a full page refresh
+     */
+    static refreshResponse(): Response;
+    static createDocument(html: string, meta?: RouteMeta, config?: KilatConfig): string;
+    private static escapeHtml;
+}
+export interface HTMXResponseOptions {
+    /** CSS selector to retarget the response to */
+    retarget?: string;
+    /** Swap method: innerHTML, outerHTML, beforeend, afterend, etc */
+    reswap?: string;
+    /** JSON string or event name to trigger on client */
+    trigger?: string;
+    /** Event to trigger after content settles */
+    triggerAfterSettle?: string;
+    /** Event to trigger after swap */
+    triggerAfterSwap?: string;
+    /** URL to redirect client to */
+    redirect?: string;
+    /** Whether to trigger a full page refresh */
+    refresh?: boolean;
+    /** URL to push into browser history */
+    pushUrl?: string;
+    /** URL to replace in browser history */
+    replaceUrl?: string;
+    /** HTTP status code */
+    status?: number;
+}

package/dist/adapters/react.d.ts

@@ -0,0 +1,7 @@
+import React from "react";
+import { PageProps, RouteMeta, KilatConfig } from "../core/types";
+export declare class ReactAdapter {
+    static renderToString(component: React.ComponentType<PageProps>, props: PageProps): Promise<string>;
+    static createDocument(html: string, meta?: RouteMeta, config?: KilatConfig): string;
+    private static escapeHtml;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/core/router.d.ts

@@ -0,0 +1,36 @@
+import { RouteMatch, KilatConfig } from "./types";
+export declare class Router {
+    private routes;
+    private config;
+    private staticPaths;
+    private serverId;
+    private fsRouter;
+    private routeCache;
+    private preloadedRoutes;
+    private routePatterns;
+    private apiRoutes;
+    private staticApiResponses;
+    private static readonly NOT_FOUND_RESPONSE;
+    private static readonly METHOD_NOT_ALLOWED_RESPONSE;
+    private static readonly INTERNAL_ERROR_RESPONSE;
+    private contextPool;
+    private poolIndex;
+    constructor(config: KilatConfig);
+    getRoutes(): Map<string, any>;
+    getStaticPaths(): Map<string, string[]>;
+    loadRoutes(): Promise<void>;
+    private preloadAllRoutes;
+    private scanAndPreloadRoutes;
+    private createRoutePattern;
+    private getRouteType;
+    matchRoute(path: string): RouteMatch | null;
+    private pathMatchesPattern;
+    handleRequest(request: Request): Promise<Response>;
+    private handleApiRouteFast;
+    private getContextFromPool;
+    private returnContextToPool;
+    private getMinimalApiContext;
+    private handleStaticFile;
+    private create404Response;
+    private renderPage;
+}

package/dist/core/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Route rendering modes:
+ * - "static": Pre-built at build time (SSG) - for known, unchanging paths
+ * - "ssr": Server-rendered on each request - for dynamic content
+ * - "api": Pure server handler, no HTML rendering - for API endpoints
+ */
+export type RenderMode = "static" | "ssr" | "api";
+export type UIFramework = "react" | "htmx";
+/**
+ * Route type classification for build/runtime decisions:
+ * - "static": Routes without dynamic segments, built at compile time
+ * - "dynamic": Routes with [param] segments, rendered at runtime
+ * - "api": Routes under /api/*, server-only handlers
+ */
+export type RouteType = "static" | "dynamic" | "api";
+export interface RouteMeta {
+    title?: string;
+    description?: string;
+    robots?: string;
+    canonical?: string;
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImage?: string;
+    twitterCard?: "summary" | "summary_large_image";
+    [key: string]: any;
+}
+export interface RouteContext {
+    request: Request;
+    params: Record<string, string>;
+    query: URLSearchParams;
+    state: ServerGlobalState;
+}
+export interface ServerGlobalState {
+    [key: string]: any;
+}
+export interface RouteExports {
+    mode?: RenderMode;
+    ui?: UIFramework;
+    load?: (ctx: RouteContext) => Promise<any> | any;
+    meta?: RouteMeta;
+    getStaticPaths?: () => Promise<string[]> | string[];
+    POST?: (ctx: RouteContext) => Promise<Response> | Response;
+    PUT?: (ctx: RouteContext) => Promise<Response> | Response;
+    DELETE?: (ctx: RouteContext) => Promise<Response> | Response;
+    PATCH?: (ctx: RouteContext) => Promise<Response> | Response;
+    default: (props: PageProps) => any;
+}
+export interface PageProps {
+    data: any;
+    params: Record<string, string>;
+    state: ServerGlobalState;
+}
+export interface RouteMatch {
+    route: string;
+    params: Record<string, string>;
+    exports: RouteExports;
+    routeType: RouteType;
+}
+export interface TailwindConfig {
+    enabled: boolean;
+    inputPath?: string;
+    cssPath: string;
+    configPath?: string;
+}
+export interface KilatConfig {
+    routesDir: string;
+    outDir: string;
+    port?: number;
+    hostname?: string;
+    dev?: boolean;
+    publicDir?: string;
+    tailwind?: TailwindConfig;
+}
+export type LoaderData<T extends (...args: any) => any> = Awaited<ReturnType<T>>;

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+export { Router } from "./core/router";
+export { KilatServer } from "./server/server";
+export { ReactAdapter } from "./adapters/react";
+export { HTMXAdapter, type HTMXResponseOptions } from "./adapters/htmx";
+export * from "./core/types";
+import { KilatServer } from "./server/server";
+import { KilatConfig } from "./core/types";
+/**
+ * Default configuration for KilatJS
+ */
+export declare const defaultConfig: KilatConfig;
+/**
+ * Create a Kilat instance with custom configuration
+ */
+export declare function createKilat(config?: Partial<KilatConfig>): KilatServer;
+/**
+ * Start the development server
+ */
+export declare function startDevServer(config?: Partial<KilatConfig>): Promise<Bun.Server<undefined>>;
+/**
+ * Build static site
+ */
+export declare function buildStatic(config?: Partial<KilatConfig>): Promise<void>;
+/**
+ * Define a route loader with type inference
+ */
+export declare function defineLoader<T>(loader: (ctx: import("./core/types").RouteContext) => Promise<T> | T): (ctx: import("./core/types").RouteContext) => Promise<T> | T;
+/**
+ * Define configuration with type inference
+ */
+export declare function defineConfig(config: Partial<KilatConfig>): Partial<KilatConfig>;
+/**
+ * Define route meta with type inference
+ */
+export declare function defineMeta(meta: import("./core/types").RouteMeta): import("./core/types").RouteMeta;
+declare const Kilat: {
+    createKilat: typeof createKilat;
+    startDevServer: typeof startDevServer;
+    buildStatic: typeof buildStatic;
+    defineConfig: typeof defineConfig;
+    defineLoader: typeof defineLoader;
+    defineMeta: typeof defineMeta;
+    defaultConfig: KilatConfig;
+};
+export default Kilat;