gorsee 0.1.0

package/src/runtime/hydration.ts

@@ -0,0 +1,95 @@
+// Hydration context -- cursor-based DOM reuse
+// During hydration, jsx() reuses server-rendered DOM nodes
+// instead of creating new ones, then attaches reactive bindings
+
+interface HydrationCursor {
+  parent: Node
+  index: number
+}
+
+const stack: HydrationCursor[] = []
+let active = false
+let mismatches = 0
+
+export function isHydrating(): boolean {
+  return active
+}
+
+export function getHydrationMismatches(): number {
+  return mismatches
+}
+
+export function enterHydration(root: Element): void {
+  active = true
+  mismatches = 0
+  stack.length = 0
+  stack.push({ parent: root, index: 0 })
+}
+
+export function exitHydration(): void {
+  active = false
+  stack.length = 0
+  if (mismatches > 0 && typeof console !== "undefined") {
+    console.warn(`[gorsee] Hydration completed with ${mismatches} mismatch(es). Server and client HTML may differ.`)
+  }
+}
+
+export function claimElement(expectedTag?: string): Element | null {
+  const cursor = stack[stack.length - 1]
+  if (!cursor) return null
+
+  // Skip whitespace-only text nodes and comments (server may differ from client)
+  while (cursor.index < cursor.parent.childNodes.length) {
+    const node = cursor.parent.childNodes[cursor.index]!
+    if (node.nodeType === 1) {
+      // Element node — check tag match if provided
+      if (expectedTag && (node as Element).tagName.toLowerCase() !== expectedTag.toLowerCase()) {
+        mismatches++
+        // Skip mismatched element and continue looking
+        cursor.index++
+        continue
+      }
+      cursor.index++
+      return node as Element
+    }
+    if (node.nodeType === 3 && node.textContent?.trim() === "") {
+      cursor.index++
+      continue
+    }
+    if (node.nodeType === 8) {
+      // Comment node -- skip
+      cursor.index++
+      continue
+    }
+    break
+  }
+  return null
+}
+
+export function claimText(): Text | null {
+  const cursor = stack[stack.length - 1]
+  if (!cursor) return null
+
+  while (cursor.index < cursor.parent.childNodes.length) {
+    const node = cursor.parent.childNodes[cursor.index]!
+    if (node.nodeType === 3) {
+      cursor.index++
+      return node as Text
+    }
+    // Skip comments
+    if (node.nodeType === 8) {
+      cursor.index++
+      continue
+    }
+    break
+  }
+  return null
+}
+
+export function pushCursor(parent: Node): void {
+  stack.push({ parent, index: 0 })
+}
+
+export function popCursor(): void {
+  stack.pop()
+}

package/src/runtime/image.ts

@@ -0,0 +1,48 @@
+// <Image> component -- optimized image rendering
+// Server: renders <img> with lazy loading, width/height, srcset
+// Prevents layout shift with explicit dimensions
+
+export interface ImageProps {
+  src: string
+  alt: string
+  width?: number
+  height?: number
+  loading?: "lazy" | "eager"
+  priority?: boolean
+  sizes?: string
+  class?: string
+  className?: string
+  [key: string]: unknown
+}
+
+export function Image(props: ImageProps): unknown {
+  const {
+    src,
+    alt,
+    width,
+    height,
+    loading: loadingProp,
+    priority,
+    sizes,
+    ...rest
+  } = props
+
+  const loading = priority ? "eager" : (loadingProp ?? "lazy")
+  const fetchpriority = priority ? "high" : undefined
+  const decoding = priority ? "sync" : "async"
+
+  const imgProps: Record<string, unknown> = {
+    src,
+    alt,
+    loading,
+    decoding,
+    ...rest,
+  }
+
+  if (width !== undefined) imgProps.width = String(width)
+  if (height !== undefined) imgProps.height = String(height)
+  if (sizes) imgProps.sizes = sizes
+  if (fetchpriority) imgProps.fetchpriority = fetchpriority
+
+  return { type: "img", props: imgProps }
+}

package/src/runtime/index.ts

@@ -0,0 +1,12 @@
+export { Suspense } from "./suspense.ts"
+export { render, hydrate } from "./client.ts"
+export { enterHydration, exitHydration, isHydrating } from "./hydration.ts"
+export { renderToString, ssrJsx, ssrJsxs } from "./server.ts"
+export { renderToStream, StreamSuspense, streamJsx, streamJsxs } from "./stream.ts"
+export { EVENT_REPLAY_SCRIPT, replayEvents, stopEventCapture } from "./event-replay.ts"
+export { Link } from "./link.ts"
+export { Head } from "./head.ts"
+export { navigate, onNavigate, beforeNavigate, getCurrentPath, prefetch, initRouter, setLoadingElement } from "./router.ts"
+export { useFormAction } from "./form.ts"
+export { island, isIsland } from "./island.ts"
+export { hydrateIslands, registerIsland } from "./island-hydrator.ts"

package/src/runtime/island-hydrator.ts

@@ -0,0 +1,84 @@
+// Client-side island hydration
+// Scans DOM for data-island elements, hydrates each independently
+// Static content around islands stays untouched (zero JS)
+
+import { enterHydration, exitHydration } from "./hydration.ts"
+import { replayEvents } from "./event-replay.ts"
+
+type IslandLoader = () => Promise<{ default: (props: Record<string, unknown>) => unknown }>
+
+const islandRegistry = new Map<string, IslandLoader>()
+
+/** Register an island component loader by name. */
+export function registerIsland(name: string, loader: IslandLoader): void {
+  islandRegistry.set(name, loader)
+}
+
+/** Parse the escaped JSON props from a data-props attribute. */
+function parseIslandProps(raw: string): Record<string, unknown> {
+  try {
+    return JSON.parse(raw) as Record<string, unknown>
+  } catch {
+    console.warn(`[gorsee] Failed to parse island props: ${raw}`)
+    return {}
+  }
+}
+
+/** Hydrate a single island element. */
+async function hydrateOne(el: Element): Promise<void> {
+  const name = el.getAttribute("data-island")
+  if (!name) return
+
+  const loader = islandRegistry.get(name)
+  if (!loader) {
+    console.warn(`[gorsee] Island "${name}" not found in registry`)
+    return
+  }
+
+  const mod = await loader()
+  const component = mod.default
+  const rawProps = el.getAttribute("data-props") ?? "{}"
+  const props = parseIslandProps(rawProps)
+
+  enterHydration(el as HTMLElement)
+  component(props)
+  exitHydration()
+
+  replayEvents(el as HTMLElement)
+}
+
+/**
+ * Hydrate all island components on the page.
+ * Finds all elements with data-island attribute and hydrates each independently.
+ * Lazy islands use IntersectionObserver to defer until visible.
+ */
+export function hydrateIslands(): void {
+  const islands = document.querySelectorAll("[data-island]")
+
+  for (let i = 0; i < islands.length; i++) {
+    const el = islands[i]!
+    const isLazy = el.hasAttribute("data-island-lazy")
+
+    if (isLazy && typeof IntersectionObserver !== "undefined") {
+      observeLazy(el)
+    } else {
+      void hydrateOne(el)
+    }
+  }
+}
+
+/** Observe a lazy island and hydrate when it enters the viewport. */
+function observeLazy(el: Element): void {
+  const observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          observer.unobserve(el)
+          void hydrateOne(el)
+        }
+      }
+    },
+    { rootMargin: "200px" },
+  )
+  observer.observe(el)
+}

package/src/runtime/island.ts

@@ -0,0 +1,88 @@
+// Island component wrapper -- marks components for client-side hydration
+// Usage: export default island(MyComponent) in route files
+// Server: renders component with data-island attribute + serialized props
+// Client: returns wrapped element for hydration
+
+import type { VNode } from "./server.ts"
+
+export interface IslandOptions {
+  lazy?: boolean // load island JS lazily (IntersectionObserver)
+}
+
+// Symbol to mark island wrappers for identification
+export const ISLAND_MARKER = Symbol("gorsee-island")
+
+interface IslandWrapper<P extends Record<string, unknown>> {
+  (props: P): unknown
+  [ISLAND_MARKER]: true
+  componentName: string
+  originalComponent: (props: P) => unknown
+  options: IslandOptions
+}
+
+/**
+ * Escape a JSON string for safe embedding in HTML data attributes.
+ * Prevents breaking out of attribute values or injecting HTML.
+ */
+function escapePropsForAttr(json: string): string {
+  return json
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+}
+
+/**
+ * Wrap a component as an island -- only this component gets hydrated on the client.
+ * Static surrounding content stays as server-rendered HTML with zero JS.
+ */
+export function island<P extends Record<string, unknown>>(
+  component: (props: P) => unknown,
+  options: IslandOptions = {},
+): IslandWrapper<P> {
+  const name = component.name || "Anonymous"
+
+  const wrapper = function islandWrapper(props: P): unknown {
+    const propsWithoutChildren = extractSerializableProps(props)
+    const serialized = escapePropsForAttr(JSON.stringify(propsWithoutChildren))
+
+    const attrs: Record<string, unknown> = {
+      "data-island": name,
+      "data-props": serialized,
+      children: component(props),
+    }
+
+    if (options.lazy) {
+      attrs["data-island-lazy"] = "true"
+    }
+
+    // On server: ssrJsx produces VNode; on client: jsx produces DOM node
+    // We return a plain object that both renderers understand
+    return { type: "div", props: attrs } as VNode
+  }
+
+  wrapper[ISLAND_MARKER] = true as const
+  wrapper.componentName = name
+  wrapper.originalComponent = component
+  wrapper.options = options
+
+  return wrapper
+}
+
+/** Extract only serializable props (skip children, functions, symbols). */
+function extractSerializableProps(
+  props: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  for (const key in props) {
+    if (key === "children") continue
+    const val = props[key]
+    if (typeof val === "function" || typeof val === "symbol") continue
+    result[key] = val
+  }
+  return result
+}
+
+export function isIsland(fn: unknown): fn is IslandWrapper<Record<string, unknown>> {
+  return typeof fn === "function" && ISLAND_MARKER in fn
+}

package/src/runtime/jsx-runtime.ts

@@ -0,0 +1,167 @@
+// Gorsee.js JSX Runtime
+// Compiles JSX to direct DOM operations with reactive bindings
+// No Virtual DOM -- signals update DOM nodes directly
+// Supports hydration mode: reuses server-rendered DOM nodes
+
+import { createEffect } from "../reactive/effect.ts"
+import { isHydrating, claimElement, claimText, pushCursor, popCursor } from "./hydration.ts"
+import { isSignal } from "./html-escape.ts"
+
+export type GorseeNode = Node | string | number | boolean | null | undefined | GorseeNode[]
+export type Component = (props: Record<string, unknown>) => GorseeNode
+
+export const Fragment = Symbol("Fragment")
+
+export interface JSXElement {
+  type: string | Component | typeof Fragment
+  props: Record<string, unknown>
+  children: unknown[]
+}
+
+function createTextNode(value: unknown): Text {
+  return document.createTextNode(String(value ?? ""))
+}
+
+function bindProperty(el: HTMLElement, key: string, value: unknown): void {
+  if (key === "children" || key === "ref") return
+
+  if (key.startsWith("on:")) {
+    el.addEventListener(key.slice(3), value as EventListener)
+    return
+  }
+
+  if (key === "className" || key === "class") {
+    if (isSignal(value)) {
+      createEffect(() => { el.className = String(value()) })
+    } else if (!isHydrating()) {
+      el.className = String(value ?? "")
+    }
+    return
+  }
+
+  if (key === "style" && typeof value === "object" && value !== null) {
+    const styles = value as Record<string, unknown>
+    for (const [prop, val] of Object.entries(styles)) {
+      if (isSignal(val)) {
+        const p = prop
+        createEffect(() => { el.style.setProperty(p, String(val())) })
+      } else if (!isHydrating()) {
+        el.style.setProperty(prop, String(val))
+      }
+    }
+    return
+  }
+
+  if (isSignal(value)) {
+    createEffect(() => { el.setAttribute(key, String(value())) })
+  } else if (!isHydrating()) {
+    if (typeof value === "boolean") {
+      if (value) el.setAttribute(key, "")
+      else el.removeAttribute(key)
+    } else if (value != null) {
+      el.setAttribute(key, String(value))
+    }
+  }
+}
+
+function hydrateChild(parent: Node, child: unknown): void {
+  if (child == null || typeof child === "boolean") return
+
+  if (Array.isArray(child)) {
+    for (const c of child) hydrateChild(parent, c)
+    return
+  }
+
+  if (typeof child === "function" && isSignal(child)) {
+    const textNode = claimText() ?? createTextNode(child())
+    createEffect(() => { textNode.textContent = String(child() ?? "") })
+    return
+  }
+
+  if (typeof child === "object" && child instanceof Node) return
+
+  // Static text -- just advance cursor
+  claimText()
+}
+
+function insertChild(parent: Node, child: unknown): void {
+  if (child == null || typeof child === "boolean") return
+
+  if (Array.isArray(child)) {
+    for (const c of child) insertChild(parent, c)
+    return
+  }
+
+  if (child instanceof Node) {
+    parent.appendChild(child)
+    return
+  }
+
+  if (isSignal(child)) {
+    const textNode = createTextNode(child())
+    parent.appendChild(textNode)
+    createEffect(() => { textNode.textContent = String(child() ?? "") })
+    return
+  }
+
+  parent.appendChild(createTextNode(child))
+}
+
+export function jsx(
+  type: string | Component | typeof Fragment,
+  props: Record<string, unknown> | null
+): Node | DocumentFragment {
+  const allProps = props ?? {}
+  const children = allProps.children
+  const hydrating = isHydrating()
+
+  // Fragment
+  if (type === Fragment) {
+    if (hydrating) {
+      if (children != null) hydrateChild(document.createDocumentFragment(), children)
+      return document.createDocumentFragment()
+    }
+    const frag = document.createDocumentFragment()
+    if (children != null) insertChild(frag, children)
+    return frag
+  }
+
+  // Component
+  if (typeof type === "function") {
+    const result = type(allProps)
+    if (result instanceof Node) return result
+    if (hydrating) return document.createDocumentFragment()
+    const wrapper = document.createDocumentFragment()
+    insertChild(wrapper, result)
+    return wrapper
+  }
+
+  // HTML element
+  if (hydrating) {
+    const el = claimElement() as HTMLElement
+    if (el) {
+      // Attach event listeners and reactive bindings to existing element
+      for (const [key, value] of Object.entries(allProps)) {
+        if (key !== "children") bindProperty(el, key, value)
+      }
+      // Hydrate children
+      if (children != null) {
+        pushCursor(el)
+        hydrateChild(el, children)
+        popCursor()
+      }
+      return el
+    }
+    // Fallback: element missing from server HTML, create it
+  }
+
+  const el = document.createElement(type)
+  for (const [key, value] of Object.entries(allProps)) {
+    if (key !== "children") bindProperty(el, key, value)
+  }
+  if (children != null) insertChild(el, children)
+  return el
+}
+
+export const jsxs = jsx
+export const jsxDEV = jsx

package/src/runtime/link.ts

@@ -0,0 +1,45 @@
+// <Link> component -- SPA navigation link with prefetch
+// Server: renders <a> tag
+// Client: renders <a> tag with router integration
+
+import { navigate, prefetch } from "./router.ts"
+
+export interface LinkProps {
+  href: string
+  children?: unknown
+  class?: string
+  className?: string
+  prefetch?: boolean | "hover" | "viewport"
+  replace?: boolean
+  target?: string
+  [key: string]: unknown
+}
+
+// Client-side Link component
+export function Link(props: LinkProps): unknown {
+  const { href, prefetch: prefetchMode, replace, children, ...rest } = props
+
+  // Eagerly prefetch if requested
+  if (prefetchMode === true && typeof window !== "undefined") {
+    prefetch(href)
+  }
+
+  return {
+    type: "a",
+    props: {
+      href,
+      "on:click": (e: MouseEvent) => {
+        if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) return
+        const target = (e.currentTarget as HTMLAnchorElement)?.target
+        if (target && target !== "_self") return
+        e.preventDefault()
+        if (replace) {
+          history.replaceState({ gorsee: true }, "", href)
+        }
+        navigate(href, !replace)
+      },
+      ...rest,
+      children,
+    },
+  }
+}