@chr33s/solarflare 0.0.2

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@chr33s/solarflare",
+  "version": "0.0.2",
+  "license": "MIT",
+  "bin": "./src/build.ts",
+  "files": [
+    "src",
+    "tsconfig.json",
+    "!src/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/solarflare.d.ts",
+      "import": "./src/worker.ts"
+    },
+    "./client": "./src/client.ts",
+    "./server": "./src/server.ts",
+    "./tsconfig.json": "./tsconfig.json"
+  },
+  "scripts": {
+    "check": "oxfmt --check && oxlint --type-aware --type-check",
+    "fix": "oxlint --type-aware --type-check --fix && oxfmt --write",
+    "test": "WRANGLER_LOG=error; node --test src/*.test.ts"
+  },
+  "dependencies": {
+    "@preact/signals": "2.8.0",
+    "lightningcss": "1.31.1",
+    "picomatch": "4.0.3",
+    "preact": "11.0.0-beta.1",
+    "preact-custom-element": "4.6.0",
+    "preact-render-to-string": "6.6.5",
+    "rolldown": "1.0.0-rc.4",
+    "turbo-stream": "3.1.0"
+  },
+  "devDependencies": {
+    "@preact/signals-debug": "1.4.1",
+    "@types/node": "25.2.3",
+    "oxfmt": "0.32.0",
+    "oxlint": "1.47.0",
+    "oxlint-tsgolint": "0.13.0",
+    "playwright": "1.58.2",
+    "typescript": "5.9.3",
+    "wrangler": "4.65.0"
+  },
+  "optionalDependencies": {
+    "ts-morph": "27.0.2"
+  },
+  "engines": {
+    "node": ">=24.12.0"
+  }
+}

package/readme.md

@@ -0,0 +1,183 @@
+> [!WARNING]  
+> Experimental: API is unstable and not production-ready.
+
+# Solarflare
+
+Cloudflare-optimized streaming SSR/CSR meta-framework built on web platform APIs, whilst retaining the DX of JSX / React|Preact.
+
+## Features
+
+- **Streaming SSR** — File-based routing with deferred promise streaming
+- **Web Components** — Hydration via `preact-custom-element`
+- **SPA Navigation** — Navigation API + View Transitions
+- **HMR** — Hot module replacement with scroll restoration
+- **Styles** — Constructable Stylesheets, critical CSS extraction
+- **Performance** — Early hints, route caching, preconnect hints, speculation rules
+- **Cloudflare** — Workers-optimized with edge caching
+- **TypeScript** — Full type safety
+
+## Requirements
+
+- [Node.js](https://nodejs.org) ≥v24.12.0
+- Modern browser (Chrome 102+, Edge 102+, Safari 15.4+)
+
+## CLI
+
+```sh
+solarflare [options]
+```
+
+| Option               | Description               |
+| -------------------- | ------------------------- |
+| `--clean`, `-c`      | Clean output before build |
+| `--debug`, `-d`      | Enable debugging          |
+| `--production`, `-p` | Optimize for production   |
+| `--serve`, `-s`      | Start dev server with HMR |
+| `--sourcemap`        | Generate source maps      |
+| `--watch`, `-w`      | Watch and rebuild         |
+
+## Conventions
+
+| Directory  | Purpose                                                 |
+| ---------- | ------------------------------------------------------- |
+| `./src`    | Original (source) human readable code                   |
+| `./dist`   | Compiled (distribution) [client, server] output code    |
+| `./public` | Static assets, copied verbatim to dist/client directory |
+
+| File           | Purpose                          |
+| -------------- | -------------------------------- |
+| `*.client.tsx` | Client component (web component) |
+| `*.server.tsx` | Server handler (Workers runtime) |
+| `_layout.tsx`  | Layout wrapper                   |
+| `_*`           | Private (not routed)             |
+| `$param`       | Dynamic segment → `:param`       |
+| `index.*`      | Directory root                   |
+
+| Path  | Purpose                                  |
+| ----- | ---------------------------------------- |
+| `/_*` | reserved internal use (e.g. `/_console`) |
+
+## API
+
+### Server Handler
+
+```tsx
+export default async function server(request: Request, params: Record<string, string>) {
+  return {
+    _status: 200,
+    _headers: { "Cache-Control": "max-age=3600" },
+    title: "Hello",
+  };
+}
+```
+
+Promise-valued props are streamed independently (deferred):
+
+```tsx
+export default async function server() {
+  const user = await fetchUser(); // blocking
+  const analytics = fetchAnalytics(); // deferred
+  const recommendations = fetchRecommendations(); // deferred
+  return { user, analytics, recommendations };
+}
+```
+
+### Client Component
+
+```tsx
+export default function Client({ title }: { title: string }) {
+  return <h1>{title}</h1>;
+}
+```
+
+### Layout
+
+```tsx
+import type { VNode } from "preact";
+import { Body, Head } from "@chr33s/solarflare/server";
+
+export default function Layout({ children }: { children: VNode }) {
+  return (
+    <html>
+      <head>
+        <Head />
+      </html>
+      <body>
+        {children}
+        <Body />
+      </body>
+    </html>
+  );
+}
+```
+
+### Deferred (Suspense like deferred renderer)
+
+```tsx
+import { Deferred } from "@chr33s/solarflare/client";
+
+<Deferred priority="high" fallback={<div>Loading additional content...</div>}>
+  ...
+</Deferred>;
+```
+
+### Configuration using meta tags
+
+```html
+<!-- router -->
+<meta name="sf:base" content="/" />
+<meta name="sf:scroll-behavior" content="auto" />
+<meta name="sf:view-transitions" content="false" />
+
+<!-- performance -->
+<meta name="sf:preconnect" content="https://cdn.example.com" />
+<meta name="sf:early-flush" content="true" />
+<meta name="sf:critical-css" content="true" />
+<meta name="sf:cache-max-age" content="300" />
+<meta name="sf:cache-swr" content="3600" />
+<meta name="sf:prefetch" content="/about, /faq, /blog/*" />
+<meta name="sf:prerender" content="/, /landing" />
+<meta name="sf:prefetch-selector" content="a.nav-link" />
+<meta name="sf:speculation-eagerness" content="moderate" />
+```
+
+### Custom Web Component
+
+```tsx
+import { define } from "@chr33s/solarflare/client";
+export default define(MyComponent, { shadow: true });
+```
+
+## Environment
+
+| File                    | Purpose                                                      |
+| ----------------------- | ------------------------------------------------------------ |
+| `WRANGLER_LOG`          | Set logging verbosity for both wrangler & console forwarding |
+| `WRANGLER_SEND_METRICS` | Disable sending anonymous usage data to Cloudflare           |
+
+## Examples
+
+- [Basic](examples/basic/readme.md) — Layouts, dynamic routes, API, components
+- [Bun](examples/bun/readme.md) — Bun runtime example
+- [Deno](examples/deno/readme.md) — Deno runtime example
+- [Minimal](examples/minimal/readme.md) — Single route
+- [Node](examples/node/readme.md) — Using `srvx` instead of Workers
+- [Shopify App](examples/shopify-app/readme.md) — Shopify app starter
+
+## Development
+
+```sh
+npm install
+npm run dev
+```
+
+## Codemod
+
+```sh
+npm install --save-optional
+npx solarflare --codemod ./app
+```
+
+## License
+
+MIT

package/src/ast.ts

@@ -0,0 +1,316 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import { parsePath, type ParsedPath, type ModuleKind } from "./paths.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export function readCompilerOptions(
+  configPath = join(__dirname, "..", "tsconfig.json"),
+  sys: ts.ParseConfigHost = ts.sys,
+) {
+  const configFile = ts.readConfigFile(configPath, (path) => sys.readFile(path));
+
+  if (configFile.error) {
+    console.warn("Failed to read tsconfig.json, using defaults");
+    return {};
+  }
+
+  const parsed = ts.parseJsonConfigFileContent(configFile.config, sys, dirname(configPath));
+
+  if (parsed.errors.length > 0) {
+    console.warn("Errors parsing tsconfig.json, using defaults");
+    return {};
+  }
+
+  return parsed.options;
+}
+
+const COMPILER_OPTIONS: ts.CompilerOptions = readCompilerOptions();
+
+export function createProgram(files: string[]) {
+  return ts.createProgram(files, COMPILER_OPTIONS);
+}
+
+export interface ExportInfo {
+  type: ts.Type;
+  signatures: readonly ts.Signature[];
+  typeString: string;
+  isFunction: boolean;
+  parameters: ParameterInfo[];
+  returnType: string | null;
+}
+
+export interface ParameterInfo {
+  name: string;
+  type: string;
+  optional: boolean;
+  properties: string[];
+}
+
+function getFirstCallSignature(type: ts.Type) {
+  const signatures = type.getCallSignatures();
+  return signatures.length > 0 ? signatures[0] : null;
+}
+
+function getSignatureParameterInfo(
+  checker: ts.TypeChecker,
+  signature: ts.Signature,
+  sourceFile: ts.SourceFile,
+) {
+  const parameters: ParameterInfo[] = [];
+
+  for (const param of signature.getParameters()) {
+    const paramType = checker.getTypeOfSymbolAtLocation(param, sourceFile);
+    const properties = paramType.getProperties().map((p) => p.getName());
+
+    parameters.push({
+      name: param.getName(),
+      type: checker.typeToString(paramType),
+      optional: !!(param.flags & ts.SymbolFlags.Optional),
+      properties,
+    });
+  }
+
+  return {
+    parameters,
+    returnType: checker.typeToString(signature.getReturnType()),
+  };
+}
+
+/** Gets detailed information about a module's default export. */
+export function getDefaultExportInfo(checker: ts.TypeChecker, sourceFile: ts.SourceFile) {
+  const symbol = checker.getSymbolAtLocation(sourceFile);
+  if (!symbol) return null;
+
+  const exports = checker.getExportsOfModule(symbol);
+  const defaultExport = exports.find((e) => e.escapedName === "default");
+  if (!defaultExport) return null;
+
+  const type = checker.getTypeOfSymbolAtLocation(defaultExport, sourceFile);
+  const signatures = type.getCallSignatures();
+  const typeString = checker.typeToString(type);
+  const signature = getFirstCallSignature(type);
+  const isFunction = !!signature;
+
+  const parameters: ParameterInfo[] = [];
+  let returnType: string | null = null;
+
+  if (isFunction && signature) {
+    const info = getSignatureParameterInfo(checker, signature, sourceFile);
+    parameters.push(...info.parameters);
+    returnType = info.returnType;
+  }
+
+  return {
+    type,
+    signatures,
+    typeString,
+    isFunction,
+    parameters,
+    returnType,
+  };
+}
+
+export interface ValidationResult {
+  file: string;
+  kind: ModuleKind;
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  exportInfo: ExportInfo | null;
+}
+
+export function validateModule(program: ts.Program, filePath: string, baseDir: string = "./src") {
+  const fullPath = join(baseDir, filePath);
+  const sourceFile = program.getSourceFile(fullPath);
+  const checker = program.getTypeChecker();
+  const parsed = parsePath(filePath);
+
+  const result: ValidationResult = {
+    file: filePath,
+    kind: parsed.kind,
+    valid: true,
+    errors: [],
+    warnings: [],
+    exportInfo: null,
+  };
+
+  if (!sourceFile) {
+    result.valid = false;
+    result.errors.push(`Source file not found: ${fullPath}`);
+    return result;
+  }
+
+  const exportInfo = getDefaultExportInfo(checker, sourceFile);
+  result.exportInfo = exportInfo;
+
+  if (!exportInfo) {
+    result.valid = false;
+    result.errors.push("Missing default export");
+    return result;
+  }
+
+  // Validate based on module kind
+  switch (parsed.kind) {
+    case "server":
+      validateServerModule(result, exportInfo);
+      break;
+    case "client":
+      validateClientModule(result, exportInfo);
+      break;
+    case "layout":
+      validateLayoutModule(result, exportInfo);
+      break;
+  }
+
+  return result;
+}
+
+function validateServerModule(result: ValidationResult, exportInfo: ExportInfo) {
+  if (!exportInfo.isFunction) {
+    result.valid = false;
+    result.errors.push("Default export must be a function");
+    return;
+  }
+
+  if (exportInfo.parameters.length < 1) {
+    result.warnings.push("Server loader should accept (request, params?, env?) parameters");
+  }
+
+  // Check first param is Request-like
+  const firstParam = exportInfo.parameters[0];
+  if (firstParam && !firstParam.type.includes("Request") && firstParam.type !== "any") {
+    result.warnings.push(`First parameter should be Request, got ${firstParam.type}`);
+  }
+}
+
+function validateClientModule(result: ValidationResult, exportInfo: ExportInfo) {
+  if (!exportInfo.isFunction) {
+    result.valid = false;
+    result.errors.push("Default export must be a function component");
+    return;
+  }
+
+  // Check return type is JSX-like
+  if (
+    exportInfo.returnType &&
+    !exportInfo.returnType.includes("VNode") &&
+    !exportInfo.returnType.includes("Element") &&
+    !exportInfo.returnType.includes("JSX") &&
+    exportInfo.returnType !== "null" &&
+    exportInfo.returnType !== "any"
+  ) {
+    result.warnings.push(`Component should return JSX, got ${exportInfo.returnType}`);
+  }
+}
+
+function validateLayoutModule(result: ValidationResult, exportInfo: ExportInfo) {
+  if (!exportInfo.isFunction) {
+    result.valid = false;
+    result.errors.push("Default export must be a function component");
+    return;
+  }
+
+  if (exportInfo.parameters.length === 0) {
+    result.warnings.push("Layout should accept { children } prop");
+    return;
+  }
+
+  // Check first param has 'children' property
+  const firstParam = exportInfo.parameters[0];
+  if (!firstParam.properties.includes("children")) {
+    result.warnings.push('Layout props should include "children"');
+  }
+}
+
+export interface ModuleEntry {
+  path: string;
+  parsed: ParsedPath;
+  validation: ValidationResult | null;
+}
+
+export function getTypeDeclaration(kind: ModuleKind) {
+  switch (kind) {
+    case "server":
+      return "(request: Request, params: Record<string, string>, env: Env) => Response | Promise<Response> | Record<string, unknown> | Promise<Record<string, unknown>>";
+    case "client":
+      return '(props: any) => import("preact").VNode';
+    case "layout":
+      return '(props: { children: import("preact").VNode }) => import("preact").VNode';
+    case "error":
+      return '(props: { error: Error; url?: URL; statusCode?: number; reset?: () => void }) => import("preact").VNode';
+    default:
+      return "unknown";
+  }
+}
+
+export function generateTypedModulesFile(entries: ModuleEntry[]) {
+  const errors: string[] = [];
+
+  // Group by kind
+  const serverModules = entries.filter((e) => e.parsed.kind === "server");
+  const clientModules = entries.filter((e) => e.parsed.kind === "client");
+  const layoutModules = entries.filter((e) => e.parsed.kind === "layout");
+  const errorModule = entries.find((e) => e.parsed.kind === "error");
+
+  // Check for validation errors
+  for (const entry of entries) {
+    if (entry.validation && !entry.validation.valid) {
+      for (const error of entry.validation.errors) {
+        errors.push(`${entry.path}: ${error}`);
+      }
+    }
+  }
+
+  // Import paths are relative from dist/ to src/
+  const generateEntries = (modules: ModuleEntry[]) =>
+    modules
+      .map((m) => `    './${m.parsed.normalized}': () => import('../src/${m.parsed.normalized}')`)
+      .join(",\n");
+
+  const errorEntry = errorModule
+    ? `() => import('../src/${errorModule.parsed.normalized}')`
+    : "undefined";
+
+  const content = `/**
+ * Auto-generated route modules
+ * Pre-resolved imports for Cloudflare Workers compatibility
+ *
+ * Module types validated via AST analysis:
+ * - Server modules: ${serverModules.length}
+ * - Client modules: ${clientModules.length}
+ * - Layout modules: ${layoutModules.length}
+ * - Error module: ${errorModule ? "yes" : "no"}
+ */
+
+type ServerLoader = ${getTypeDeclaration("server")}
+type ClientComponent = ${getTypeDeclaration("client")}
+type LayoutComponent = ${getTypeDeclaration("layout")}
+type ErrorComponent = ${getTypeDeclaration("error")}
+
+interface ModuleMap {
+  server: Record<string, () => Promise<{ default: ServerLoader }>>
+  client: Record<string, () => Promise<{ default: ClientComponent }>>
+  layout: Record<string, () => Promise<{ default: LayoutComponent }>>
+  error?: () => Promise<{ default: ErrorComponent }>
+}
+
+const modules: ModuleMap = {
+  server: {
+${generateEntries(serverModules)}
+  },
+  client: {
+${generateEntries(clientModules)}
+  },
+  layout: {
+${generateEntries(layoutModules)}
+  },
+  error: ${errorEntry},
+}
+
+export default modules
+`;
+
+  return { content, errors };
+}