@kudzujs/core 0.4.1 → 0.4.3

package/README.md

@@ -77,7 +77,7 @@ export default function HomePage() {
 npm run dev
 ```
 
-Pages live in `src/pages`; `index.tsx` maps to `/`. Production output is written to `dist/`.
+Pages live in `src/pages`; `index.tsx` maps to `/`. `npm run dev` serves locally on `127.0.0.1`, reloads the browser after successful rebuilds, and shows build failures in an error overlay. Across that full-page reload, compatible Kudzu logical state is briefly preserved by route-unique state variable name for the current pathname, query, and hash, including controlled properties, conditions, and keyed-list arrays. Renamed, removed, and duplicate-named state is skipped. Uncontrolled DOM state, focus, selection, and imperative DOM mutations are not preserved. Set `PORT` to change the default port of `3000`. The development client and state snapshot are dev-only; production output in `dist/` is unaffected.
 
 ## State Semantics
 

package/framework/README.md

@@ -9,8 +9,9 @@
 - `list-runtime.js`: optional keyed list validation, external item-expression evaluation, dynamic item-handler scopes, moves, and cleanup.
 - `serialization.js`: capture deserialization shared by binding and native handlers.
 - `native-runtime.js`: optional runtime for normal synchronous and asynchronous ESM handlers.
+- `dev-state.js`: dev-only, short-lived logical-state snapshot validation and restoration.
 - `*.d.ts`: public TypeScript and JSX declarations.
 
-Static routes receive no browser runtime. Command routes receive `runtime.js`; reactive attributes and conditions add `binding-runtime.js`; keyed lists add `list-runtime.js`; native handlers add `native-runtime.js`. Capability runtimes share state and lifecycle hooks through `shared-runtime.js`. Generated evaluators live under `dist/assets/handlers/`.
+Static routes receive no browser runtime. Command routes receive `runtime.js`; reactive attributes and conditions add `binding-runtime.js`; keyed lists add `list-runtime.js`; native handlers add `native-runtime.js`. Capability runtimes share state and lifecycle hooks through `shared-runtime.js`. Generated evaluators live under `dist/assets/handlers/`. The dev server derives stable state identities from route-unique variable names in each route plan; every state sharing a duplicate name is omitted. It then injects its SSE reload, short-lived full-URL-scoped logical-state snapshot, and build-error client into responses only, never into `dist/`. Snapshots are consumed even when the next page is static or broken. Reload restoration covers compatible framework state, not uncontrolled DOM state, focus, selection, or imperative mutations.
 
 Page `metadata` can emit description, canonical, favicon, manifest, Open Graph, and Twitter Card tags without a client runtime.

package/framework/build.mjs

@@ -1,9 +1,11 @@
 import { createServer } from "node:http"
+import { randomUUID } from "node:crypto"
 import { cp, mkdir, readFile, readdir, rm, stat, watch, writeFile } from "node:fs/promises"
 import { extname, join, relative, resolve, sep } from "node:path"
 import { pathToFileURL } from "node:url"
 import ts from "typescript"
 import { renderPage } from "./core.mjs"
+import { stateSchema } from "./dev-state.js"
 
 const root = process.cwd()
 const sourceDirectory = join(root, "src")
@@ -11,6 +13,8 @@ const pagesDirectory = join(sourceDirectory, "pages")
 const workDirectory = join(root, ".kudzu")
 const outputDirectory = join(root, "dist")
 
+const devClient = (session, revision, schema) => `<script>(()=>{const show=event=>{let box=document.getElementById("__kudzu_error");if(!box){box=document.createElement("div");box.id="__kudzu_error";box.setAttribute("role","alert");box.setAttribute("aria-live","assertive");box.style.cssText="position:fixed;inset:0;z-index:2147483647;overflow:auto;padding:2rem;background:#200;color:#fff;font:16px/1.5 ui-monospace,monospace";const title=document.createElement("strong"),text=document.createElement("pre");title.textContent="Kudzu build error";text.style.whiteSpace="pre-wrap";box.append(title,text);document.body.append(box)}box.querySelector("pre").textContent=event.data};const schema=${inlineJson(schema)},route=location.pathname+location.search+location.hash,urls=[...document.querySelectorAll('script[type="module"][src]')].map(node=>node.src).filter(url=>/\\/assets\\/kudzu(?:-(?:binding|list|native))?\\.js$/.test(new URL(url).pathname));const devImport=import("/__kudzu_dev.js"),runtimeImports=Promise.allSettled(urls.map(url=>import(url)));const ready=(async()=>{const dev=await devImport,modules=await runtimeImports,runtime=modules.find(result=>result.status==="fulfilled"&&result.value.browserState instanceof Map&&typeof result.value.commitDom==="function")?.value;try{dev.restoreState(sessionStorage,route,runtime?.browserState,schema,runtime?.commitDom)}catch{}return{dev,runtime}})().catch(()=>({}));const events=new EventSource("/__kudzu_reload?session=${session}&revision=${revision}");let reloading=false;events.addEventListener("reload",async()=>{if(reloading)return;reloading=true;try{const{dev,runtime}=await ready;dev?.snapshotState(sessionStorage,route,runtime?.browserState,schema)}catch{}location.reload()});events.addEventListener("build-error",show)})()</script>`
+
 export async function build({ quiet = false } = {}) {
   await rm(workDirectory, { recursive: true, force: true })
   await rm(outputDirectory, { recursive: true, force: true })
@@ -108,44 +112,144 @@ function specializeRuntime(source, events, hasStateSeed) {
     .replace("  if (initialState) for (const [id, value] of JSON.parse(initialState)) browserState.set(id, value)\n", "")
 }
 
-export async function dev() {
-  await build()
+export function parseDevPort(value) {
+  if (value === undefined || value.trim() === "") return 3000
+  if (!/^\d+$/.test(value)) throw new Error(`Invalid dev server port: ${value}`)
+  const port = Number(value)
+  if (port > 65535) throw new Error(`Invalid dev server port: ${value}`)
+  return port
+}
+
+export async function dev({ port = parseDevPort(process.env.PORT) } = {}) {
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`Invalid dev server port: ${port}`)
+
+  let buildError
+  let revision = 0
+  const session = randomUUID()
+  try {
+    await build()
+    revision++
+  } catch (error) {
+    buildError = errorText(error)
+    console.error(error)
+  }
+
+  const clients = new Set()
 
   const server = createServer(async (request, response) => {
     try {
-      const pathname = decodeURIComponent(new URL(request.url, "http://localhost").pathname)
+      const url = new URL(request.url, "http://localhost")
+      const pathname = decodeURIComponent(url.pathname)
+      if (pathname === "/__kudzu_reload") {
+        response.writeHead(200, {
+          "content-type": "text/event-stream; charset=utf-8",
+          "cache-control": "no-cache, no-transform",
+          connection: "keep-alive"
+        })
+        response.write(": connected\n\n")
+        clients.add(response)
+        request.on("close", () => clients.delete(response))
+        if (buildError) sendEvent(response, "build-error", buildError)
+        else if (url.searchParams.get("session") !== session || url.searchParams.get("revision") !== String(revision)) sendEvent(response, "reload")
+        return
+      }
+      if (pathname === "/__kudzu_dev.js") {
+        response.writeHead(200, { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-store" })
+        response.end(await readFile(new URL("./dev-state.js", import.meta.url)))
+        return
+      }
+
       const relativePath = pathname.replace(/^\/+/, "")
       let file = resolve(outputDirectory, relativePath)
       if (!file.startsWith(`${outputDirectory}${sep}`) && file !== outputDirectory) throw new Error("Invalid path")
 
       if ((await exists(file)) && (await stat(file)).isDirectory()) file = join(file, "index.html")
       if (!(await exists(file)) && !extname(file)) file = join(file, "index.html")
-      const content = await readFile(file)
-      response.writeHead(200, { "content-type": contentType(file) })
+      const isHtml = extname(file) === ".html"
+      const content = isHtml
+        ? injectDevClient(buildError ? errorPage(buildError) : await readFile(file, "utf8"), session, revision, buildError ? [] : await devSchema(pathname))
+        : await readFile(file)
+      response.writeHead(200, {
+        "content-type": contentType(file),
+        "cache-control": "no-store"
+      })
       response.end(content)
     } catch {
-      response.writeHead(404, { "content-type": "text/plain; charset=utf-8" })
+      response.writeHead(404, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" })
       response.end("Not found")
     }
   })
 
-  server.listen(3000, () => console.log("Kudzu dev server: http://localhost:3000"))
+  server.listen(port, "127.0.0.1", () => console.log(`Kudzu dev server: http://127.0.0.1:${server.address().port}`))
 
   let timer
-  const watcher = watch(sourceDirectory, { recursive: true })
-  for await (const event of watcher) {
-    clearTimeout(timer)
-    timer = setTimeout(async () => {
+  let rebuilding = false
+  let pending = false
+  let changedFile
+  const rebuild = async () => {
+    if (rebuilding) {
+      pending = true
+      return
+    }
+    rebuilding = true
+    do {
+      pending = false
       try {
         await build({ quiet: true })
-        console.log(`Rebuilt after ${event.filename ?? "source change"}`)
+        buildError = undefined
+        revision++
+        console.log(`Rebuilt after ${changedFile ?? "source change"}`)
+        for (const client of clients) sendEvent(client, "reload")
       } catch (error) {
+        buildError = errorText(error)
         console.error(error)
+        for (const client of clients) sendEvent(client, "build-error", buildError)
       }
-    }, 80)
+    } while (pending)
+    rebuilding = false
+  }
+  const watcher = watch(sourceDirectory, { recursive: true })
+  for await (const event of watcher) {
+    changedFile = event.filename
+    clearTimeout(timer)
+    timer = setTimeout(rebuild, 80)
+  }
+}
+
+function injectDevClient(html, session, revision, schema) {
+  return `${html}${devClient(session, revision, schema)}`
+}
+
+async function devSchema(pathname) {
+  try {
+    const plan = JSON.parse(await readFile(join(workDirectory, "kudzu-plan.json"), "utf8"))
+    const route = pathname.replace(/\/(?:index\.html)?$/, "") || "/"
+    return stateSchema(plan.routes.find(entry => entry.route === route)?.states ?? [])
+  } catch {
+    return []
   }
 }
 
+function inlineJson(value) {
+  return JSON.stringify(value).replaceAll("<", "\\u003c").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029")
+}
+
+function errorPage(error) {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Kudzu build error</title></head><body><div id="__kudzu_error" role="alert" aria-live="assertive" style="position:fixed;inset:0;overflow:auto;padding:2rem;background:#200;color:#fff;font:16px/1.5 ui-monospace,monospace"><strong>Kudzu build error</strong><pre style="white-space:pre-wrap">${escapeHtml(error)}</pre></div></body></html>`
+}
+
+function errorText(error) {
+  return String(error?.message ?? error)
+}
+
+function sendEvent(response, event, data = "") {
+  response.write(`event: ${event}\n${String(data).replaceAll("\r", "").split("\n").map(line => `data: ${line}\n`).join("")}\n`)
+}
+
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
+}
+
 async function compile(file) {
   const source = await readFile(file, "utf8")
   const nativeHandlers = []

package/framework/dev-state.js

@@ -0,0 +1,98 @@
+const maxAge = 10000
+
+export function stateSchema(states) {
+  const occurrences = new Map()
+  for (const { name } of states) if (typeof name === "string") occurrences.set(name, (occurrences.get(name) ?? 0) + 1)
+  return states.flatMap(({ id, name }) => {
+    return typeof id === "string" && occurrences.get(name) === 1 ? [[id, name]] : []
+  })
+}
+
+export function snapshotState(storage, route, state, schema, now = Date.now()) {
+  try {
+    storage.removeItem(storageKey(route))
+  } catch {
+    return false
+  }
+  try {
+    const identities = new Map(schema)
+    const values = [...state].flatMap(([id, value]) => {
+      const identity = identities.get(id)
+      return typeof identity === "string" && jsonSafe(value) ? [[identity, value]] : []
+    })
+    if (values.length) storage.setItem(storageKey(route), JSON.stringify({ time: now, values }))
+    return values.length > 0
+  } catch {
+    return false
+  }
+}
+
+export function restoreState(storage, route, state, schema, commit, now = Date.now()) {
+  let snapshot
+  try {
+    const raw = storage.getItem(storageKey(route))
+    if (raw === null) return []
+    storage.removeItem(storageKey(route))
+    snapshot = JSON.parse(raw)
+  } catch {
+    return []
+  }
+
+  if (!(state instanceof Map) || !Array.isArray(schema) || typeof commit !== "function") return []
+  if (!snapshot || !Number.isFinite(snapshot.time) || now < snapshot.time || now - snapshot.time > maxAge || !Array.isArray(snapshot.values)) return []
+  const ids = new Map(schema.flatMap(entry => Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string" && typeof entry[1] === "string" ? [[entry[1], entry[0]]] : []))
+  const changes = []
+  const seen = new Set()
+  for (const entry of snapshot.values) {
+    if (!Array.isArray(entry) || entry.length !== 2) continue
+    const [identity, value] = entry
+    const id = ids.get(identity)
+    if (typeof identity !== "string" || seen.has(identity) || !state.has(id) || !jsonSafe(value) || shape(value) !== shape(state.get(id))) continue
+    seen.add(identity)
+    changes.push({ id, value, original: state.get(id) })
+  }
+  for (const { id, value } of changes) state.set(id, value)
+  try {
+    for (const { id } of changes) commit(id, state.get(id))
+  } catch {
+    for (const { id, original } of changes) state.set(id, original)
+    for (const { id } of changes) {
+      try { commit(id, state.get(id)) } catch {}
+    }
+    return []
+  }
+  return changes.map(({ id }) => id)
+}
+
+function storageKey(route) {
+  return `__kudzu_state:${route}`
+}
+
+function shape(value) {
+  if (Array.isArray(value)) return "array"
+  if (value === null) return "null"
+  return typeof value === "object" ? "object" : typeof value
+}
+
+function jsonSafe(value, seen = new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true
+  if (typeof value === "number") return Number.isFinite(value) && !Object.is(value, -0)
+  if (!value || typeof value !== "object" || seen.has(value) || Object.getOwnPropertySymbols(value).length) return false
+  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype) return false
+
+  const descriptors = Object.getOwnPropertyDescriptors(value)
+  if (Array.isArray(value)) {
+    if (Object.keys(descriptors).some(key => key !== "length" && !/^(0|[1-9]\d*)$/.test(key))) return false
+    if (Object.keys(value).length !== value.length) return false
+  }
+  seen.add(value)
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (Array.isArray(value) && key === "length") continue
+    if (!descriptor.enumerable || !("value" in descriptor) || !jsonSafe(descriptor.value, seen)) {
+      seen.delete(value)
+      return false
+    }
+  }
+  seen.delete(value)
+  return true
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",