murasaki 0.0.3 → 0.0.4

package/bin/murasaki.js

@@ -2,10 +2,9 @@
 // Murasaki CLI entry point.
 // Usage: murasaki dev
 
-import 'tsx/esm'  // Register the TS+JSX ESM loader
-import { fileURLToPath } from 'node:url'
+import 'tsx/esm' // Register the TS+JSX ESM loader
 import { dirname, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const cmd = process.argv[2]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "murasaki",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "The desktop framework for Next.js developers. Node-powered. WebView-thin. No Rust. No Chromium.",
   "keywords": [
     "desktop",
@@ -39,7 +39,11 @@
     "LICENSE"
   ],
   "scripts": {
-    "example:app-router": "cd examples/app-router && pnpm dev"
+    "example:app-router": "cd examples/app-router && pnpm dev",
+    "check": "biome check",
+    "lint": "biome lint",
+    "format": "biome format --write",
+    "fix": "biome check --write"
   },
   "dependencies": {
     "@webviewjs/webview": "^0.3.2",
@@ -48,6 +52,8 @@
     "tsx": "^4.22.4"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.1",
+    "@types/node": "^26.0.1",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "typescript": "^6.0.3"

package/src/cli/colors.ts

@@ -0,0 +1,16 @@
+// ANSI truecolor palette (Oomurasaki) + helper.
+
+export const BRIGHT = '\x1b[38;2;168;85;247m'
+export const DEEP = '\x1b[38;2;91;33;182m'
+export const CREAM = '\x1b[38;2;250;245;232m'
+export const DARK = '\x1b[38;2;59;7;100m'
+export const DIM = '\x1b[38;2;136;136;153m'
+export const GREEN = '\x1b[38;2;76;175;80m'
+export const RED = '\x1b[38;2;239;68;68m'
+export const BOLD = '\x1b[1m'
+export const RESET = '\x1b[0m'
+
+export const noColor = Boolean(process.env.NO_COLOR) || !process.stdout.isTTY
+
+/** Wrap an ANSI escape; returns '' if colors are disabled. */
+export const c = (code: string): string => (noColor ? '' : code)

package/src/cli/log.ts

@@ -0,0 +1,42 @@
+// Banner + status output for the dev runner.
+
+import { projectRoot, VERSION, WEBVIEW_ENGINE } from '../env.ts'
+import { BOLD, BRIGHT, c, DIM, GREEN, RED, RESET } from './colors.ts'
+
+const out = (s: string) => process.stdout.write(s)
+
+export function printBanner(winTitle: string, winSize: { width: number; height: number }) {
+  out('\n')
+  out(`   ${c(BOLD)}${c(BRIGHT)}🦋 Murasaki${c(RESET)} ${c(DIM)}${VERSION}${c(RESET)}\n\n`)
+  out(`   ${c(DIM)}-${c(RESET)} ${c(DIM)}Project    ${c(RESET)}${projectRoot}\n`)
+  out(
+    `   ${c(DIM)}-${c(RESET)} ${c(DIM)}Window     ${c(RESET)}${winTitle} ${c(DIM)}(${winSize.width}×${winSize.height})${c(RESET)}\n`,
+  )
+  out(`   ${c(DIM)}-${c(RESET)} ${c(DIM)}Webview    ${c(RESET)}${WEBVIEW_ENGINE}\n`)
+  out(`   ${c(DIM)}-${c(RESET)} ${c(DIM)}Runtime    ${c(RESET)}Node ${process.version}\n`)
+  out(
+    `   ${c(DIM)}-${c(RESET)} ${c(DIM)}Mode       ${c(RESET)}development ${c(DIM)}(HMR active)${c(RESET)}\n\n`,
+  )
+}
+
+export function printShortcuts() {
+  out(
+    `   ${c(DIM)}Shortcuts  ${c(RESET)}${c(BOLD)}o${c(RESET)} ${c(DIM)}open${c(RESET)}   ${c(BOLD)}r${c(RESET)} ${c(DIM)}restart${c(RESET)}   ${c(BOLD)}q${c(RESET)} ${c(DIM)}quit${c(RESET)}\n\n`,
+  )
+}
+
+export const printStarting = () => out(` ${c(DIM)}○${c(RESET)} Starting...\n`)
+export const printReady = (ms: number) =>
+  out(
+    ` ${c(GREEN)}${c(BOLD)}✓${c(RESET)} ${c(BOLD)}Ready${c(RESET)} ${c(DIM)}in ${ms}ms${c(RESET)}\n`,
+  )
+export const printOpened = () => out(` ${c(GREEN)}${c(BOLD)}✓${c(RESET)} Window opened\n`)
+export const printClosed = () =>
+  out(
+    ` ${c(DIM)}○${c(RESET)} Window closed   ${c(DIM)}— press ${c(RESET)}${c(BOLD)}o${c(RESET)}${c(DIM)} to re-open, ${c(RESET)}${c(BOLD)}q${c(RESET)}${c(DIM)} to quit${c(RESET)}\n`,
+  )
+export const printReloaded = (file: string) =>
+  out(` ${c(BRIGHT)}${c(BOLD)}↻${c(RESET)} Reloaded ${c(DIM)}${file}${c(RESET)}\n`)
+export const printBye = () => out(`\n ${c(DIM)}Bye 🦋${c(RESET)}\n\n`)
+export const printHint = (msg: string) => out(` ${c(DIM)}· ${msg}${c(RESET)}\n`)
+export const printError = (msg: string) => out(` ${c(RED)}${c(BOLD)}✗${c(RESET)} ${msg}\n`)

package/src/dev.tsx

@@ -1,267 +1,60 @@
 // src/dev.tsx
 // Murasaki dev runner — Next.js-like file-based routing without Next.js.
 //
-// Reads the consumer's app/ directory:
-//   app/layout.tsx   (optional)
-//   app/page.tsx     (required)
+// Reads the consumer's src/ directory:
+//   src/layout.tsx   (optional, can export `metadata`)
+//   src/app.tsx      (required)
+//   src/globals.css  (optional, auto-injected)
 //
-// Renders <Layout><Page /></Layout> with React, ships HTML to the WebView,
+// Renders <Layout><App /></Layout> with React, ships HTML to the WebView,
 // and reloads in place on file change.
 
-import { Application, ControlFlow } from '@webviewjs/webview'
-import { existsSync, readFileSync, watch } from 'node:fs'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-import { dirname, join } from 'node:path'
-import { createElement, type ComponentType, type ReactNode } from 'react'
-import { renderToStaticMarkup } from 'react-dom/server'
-
-// ── ANSI ──────────────────────────────────────────────────────────────
-const BRIGHT = '\x1b[38;2;168;85;247m'
-const DIM    = '\x1b[38;2;136;136;153m'
-const GREEN  = '\x1b[38;2;76;175;80m'
-const RED    = '\x1b[38;2;239;68;68m'
-const BOLD   = '\x1b[1m'
-const RESET  = '\x1b[0m'
-const noColor = process.env.NO_COLOR || !process.stdout.isTTY
-const c = (code: string) => (noColor ? '' : code)
-
-// ── Project paths ─────────────────────────────────────────────────────
-const projectRoot = process.cwd()
-const SRC_DIR        = join(projectRoot, 'src')
-const APP_PATH       = join(SRC_DIR, 'app.tsx')
-const LAYOUT_PATH    = join(SRC_DIR, 'layout.tsx')
-const GLOBALS_CSS    = join(SRC_DIR, 'globals.css')
-
-// ── Resolve murasaki version (for the banner) ─────────────────────────
-const __dirname = dirname(fileURLToPath(import.meta.url))
-let VERSION = '0.0.0'
-try {
-  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'))
-  VERSION = pkg.version || '0.0.0'
-} catch {}
-
-const WEBVIEW_ENGINE = (() => {
-  switch (process.platform) {
-    case 'darwin': return 'WKWebView (macOS)'
-    case 'win32':  return 'WebView2 (Windows)'
-    case 'linux':  return 'WebKitGTK (Linux)'
-    default:       return `OS native (${process.platform})`
-  }
-})()
-
-const DEFAULT_WIN_TITLE = 'Murasaki App'
-const DEFAULT_WIN_SIZE  = { width: 1280, height: 800 }
-const START_AT          = Date.now()
-const isDev             = process.env.MURASAKI_DEV === '1' || true  // dev runner always = dev
-
-// Active window config (mutated when metadata is read)
-let winTitle = DEFAULT_WIN_TITLE
-let winSize  = { ...DEFAULT_WIN_SIZE }
-
-// ── Banner ────────────────────────────────────────────────────────────
-function printBanner() {
-  process.stdout.write('\n')
-  process.stdout.write(`   ${c(BOLD)}${c(BRIGHT)}🦋 Murasaki${c(RESET)} ${c(DIM)}${VERSION}${c(RESET)}\n\n`)
-  process.stdout.write(`   ${c(DIM)}-${c(RESET)} ${c(DIM)}Project    ${c(RESET)}${projectRoot}\n`)
-  process.stdout.write(`   ${c(DIM)}-${c(RESET)} ${c(DIM)}Window     ${c(RESET)}${winTitle} ${c(DIM)}(${winSize.width}×${winSize.height})${c(RESET)}\n`)
-  process.stdout.write(`   ${c(DIM)}-${c(RESET)} ${c(DIM)}Webview    ${c(RESET)}${WEBVIEW_ENGINE}\n`)
-  process.stdout.write(`   ${c(DIM)}-${c(RESET)} ${c(DIM)}Runtime    ${c(RESET)}Node ${process.version}\n`)
-  process.stdout.write(`   ${c(DIM)}-${c(RESET)} ${c(DIM)}Mode       ${c(RESET)}development ${c(DIM)}(HMR active)${c(RESET)}\n\n`)
-}
-function printShortcuts() { process.stdout.write(`   ${c(DIM)}Shortcuts  ${c(RESET)}${c(BOLD)}o${c(RESET)} ${c(DIM)}open${c(RESET)}   ${c(BOLD)}r${c(RESET)} ${c(DIM)}restart${c(RESET)}   ${c(BOLD)}q${c(RESET)} ${c(DIM)}quit${c(RESET)}\n\n`) }
-function printStarting() { process.stdout.write(` ${c(DIM)}○${c(RESET)} Starting...\n`) }
-function printReady(ms: number) { process.stdout.write(` ${c(GREEN)}${c(BOLD)}✓${c(RESET)} ${c(BOLD)}Ready${c(RESET)} ${c(DIM)}in ${ms}ms${c(RESET)}\n`) }
-function printOpened()   { process.stdout.write(` ${c(GREEN)}${c(BOLD)}✓${c(RESET)} Window opened\n`) }
-function printClosed()   { process.stdout.write(` ${c(DIM)}○${c(RESET)} Window closed   ${c(DIM)}— press ${c(RESET)}${c(BOLD)}o${c(RESET)}${c(DIM)} to re-open, ${c(RESET)}${c(BOLD)}q${c(RESET)}${c(DIM)} to quit${c(RESET)}\n`) }
-function printReloaded(file: string) { process.stdout.write(` ${c(BRIGHT)}${c(BOLD)}↻${c(RESET)} Reloaded ${c(DIM)}${file}${c(RESET)}\n`) }
-function printBye()      { process.stdout.write(`\n ${c(DIM)}Bye 🦋${c(RESET)}\n\n`) }
-function printHint(msg: string) { process.stdout.write(` ${c(DIM)}· ${msg}${c(RESET)}\n`) }
-function printError(msg: string) { process.stdout.write(` ${c(RED)}${c(BOLD)}✗${c(RESET)} ${msg}\n`) }
-
-// ── Routing: load app/page.tsx (+ optional app/layout.tsx) ────────────
-type ReactComponent = ComponentType<{ children?: ReactNode }>
-
-type AppMetadata = {
-  title?: string
-  description?: string
-  window?: { title?: string; width?: number; height?: number }
-}
-
-type LayoutModule = { component: ReactComponent; metadata?: AppMetadata } | null
-
-async function dynImport(path: string) {
-  // Cache-bust so file edits are picked up without restarting the process.
-  const url = pathToFileURL(path).href + `?v=${Date.now()}`
-  return import(url)
-}
-
-async function loadApp(): Promise<ReactComponent | null> {
-  if (!existsSync(APP_PATH)) return null
-  const mod = await dynImport(APP_PATH)
-  return mod.default as ReactComponent
-}
-
-async function loadLayout(): Promise<LayoutModule> {
-  if (!existsSync(LAYOUT_PATH)) return null
-  const mod = await dynImport(LAYOUT_PATH)
-  if (!mod.default) return null
-  return { component: mod.default as ReactComponent, metadata: mod.metadata as AppMetadata | undefined }
-}
-
-function loadGlobalsCss(): string {
-  if (!existsSync(GLOBALS_CSS)) return ''
-  try { return readFileSync(GLOBALS_CSS, 'utf8') } catch { return '' }
-}
-
-function escapeHtml(s: string) {
-  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
-}
-
-async function renderApp(): Promise<{ html: string; metadata?: AppMetadata }> {
-  const App = await loadApp()
-  if (!App) {
-    return { html: '<!doctype html><html><body style="font-family:system-ui;padding:40px;"><h1 style="color:#A855F7">src/app.tsx not found</h1><p>Create one and the window will reload.</p></body></html>' }
-  }
-  const layoutData = await loadLayout()
-  const metadata = layoutData?.metadata
-  const appEl = createElement(App)
-  const tree = layoutData ? createElement(layoutData.component, null, appEl) : appEl
-  let html = '<!doctype html>' + renderToStaticMarkup(tree)
-
-  // Inject <title> + <meta description> from metadata if not present in head
-  const headInjects: string[] = []
-  if (metadata?.title && !/<title>.*?<\/title>/i.test(html)) {
-    headInjects.push(`<title>${escapeHtml(metadata.title)}</title>`)
-  }
-  if (metadata?.description && !/<meta[^>]+name=["']description["']/i.test(html)) {
-    headInjects.push(`<meta name="description" content="${escapeHtml(metadata.description)}">`)
-  }
-
-  // Inject src/globals.css (auto, like Next.js's import './globals.css')
-  const css = loadGlobalsCss()
-  if (css) {
-    headInjects.push(`<style data-murasaki="globals.css">${css}</style>`)
-  }
-
-  if (headInjects.length) {
-    const blob = headInjects.join('')
-    if (html.includes('</head>')) {
-      html = html.replace('</head>', blob + '</head>')
-    } else {
-      html = html.replace('<body', blob + '<body')
-    }
-  }
-
-  return { html, metadata }
-}
-
-// ── Window lifecycle ──────────────────────────────────────────────────
-const app = new Application({ controlFlow: ControlFlow.Wait })
-let win: ReturnType<typeof app.createBrowserWindow> | null = null
-let webview: ReturnType<NonNullable<typeof win>['createWebview']> | null = null
-
-app.onEvent((event) => {
-  const kind = event && ((event as any).kind || (event as any).event)
-  if (kind === 'window-close-requested') {
-    // Dispose the window so the OS close completes — without this the
-    // close button hangs / appears frozen.
-    if (win) {
-      try { win.dispose() } catch {}
-    }
-    win = null
-    webview = null
-    printClosed()
-  }
-})
-
-function applyMetadataToWindowConfig(metadata?: AppMetadata) {
-  if (!metadata) return
-  if (metadata.window?.title) winTitle = metadata.window.title
-  else if (metadata.title)    winTitle = metadata.title
-  if (metadata.window?.width)  winSize.width  = metadata.window.width
-  if (metadata.window?.height) winSize.height = metadata.window.height
-}
-
-async function openWindow() {
-  if (win) { printHint('Window is already open'); return }
-  // Render first so we can read metadata and apply window config
-  const { html, metadata } = await renderApp()
-  applyMetadataToWindowConfig(metadata)
-  win = app.createBrowserWindow({
-    title: winTitle,
-    width: winSize.width,
-    height: winSize.height,
-  })
-  webview = win.createWebview({ html })
-  printOpened()
-}
-
-function closeWindow() {
-  if (!win) return
-  try { win.dispose() } catch {}
-  win = null
-  webview = null
-}
-
-async function reload(triggerFile: string) {
-  if (!webview) return
-  try {
-    const { html } = await renderApp()
-    webview.loadHtml(html)
-    printReloaded(triggerFile.replace(projectRoot + '/', ''))
-  } catch (e: any) {
-    printError(`Reload failed: ${e.message}`)
-  }
-}
-
-// ── File watcher (HMR for src/) ───────────────────────────────────────
-function setupHmr() {
-  if (!existsSync(SRC_DIR)) {
-    printHint('src/ directory not found — nothing to watch')
-    return
-  }
-  let debounce: NodeJS.Timeout | null = null
-  let lastFile = ''
-  try {
-    watch(SRC_DIR, { recursive: true }, (_event, filename) => {
-      if (!filename) return
-      if (debounce) clearTimeout(debounce)
-      lastFile = filename
-      debounce = setTimeout(() => { reload(lastFile) }, 80)
-    })
-  } catch (e: any) {
-    printHint(`HMR watcher failed: ${e.message}`)
-  }
-}
-
-// ── Keyboard shortcuts ────────────────────────────────────────────────
-function setupShortcuts() {
-  if (!process.stdin.isTTY) return
-  process.stdin.setRawMode(true)
-  process.stdin.resume()
-  process.stdin.setEncoding('utf8')
-  process.stdin.on('data', (key: string) => {
-    if (key === 'o' || key === 'O') {
-      openWindow()
-    } else if (key === 'r' || key === 'R') {
-      closeWindow()
-      openWindow()
-    } else if (key === 'q' || key === 'Q' || key === '' /* Ctrl+C */) {
-      printBye()
-      try { process.stdin.setRawMode(false) } catch {}
-      try { app.exit() } catch {}
-      process.exit(0)
-    }
-  })
-}
-
-// ── Boot ──────────────────────────────────────────────────────────────
-printBanner()
+import {
+  printBanner,
+  printBye,
+  printOpened,
+  printReady,
+  printShortcuts,
+  printStarting,
+} from './cli/log.ts'
+import { setupHmr } from './runtime/hmr.ts'
+import { setupShortcuts, teardownStdin } from './runtime/shortcuts.ts'
+import {
+  closeWindow,
+  exitApp,
+  getConfig,
+  openWindow,
+  reloadWindow,
+  runApp,
+} from './runtime/window.ts'
+
+const startAt = Date.now()
+
+// Boot: render once (applies metadata) → banner → ready
+await openWindow()
+printBanner(getConfig().title, getConfig())
 printShortcuts()
 printStarting()
-await openWindow()
-printReady(Date.now() - START_AT)
-setupShortcuts()
-setupHmr()
+printReady(Date.now() - startAt)
+
+setupShortcuts({
+  onOpen: () => {
+    void openWindow().then(printOpened)
+  },
+  onRestart: () => {
+    closeWindow()
+    void openWindow().then(printOpened)
+  },
+  onQuit: () => {
+    printBye()
+    teardownStdin()
+    exitApp()
+    process.exit(0)
+  },
+})
+
+setupHmr((file) => {
+  void reloadWindow(file)
+})
 
-app.run()
+runApp()

package/src/env.ts

@@ -0,0 +1,37 @@
+// Project paths + version + platform — resolved once at boot.
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const projectRoot = process.cwd()
+export const SRC_DIR = join(projectRoot, 'src')
+export const APP_PATH = join(SRC_DIR, 'app.tsx')
+export const LAYOUT_PATH = join(SRC_DIR, 'layout.tsx')
+export const GLOBALS_CSS = join(SRC_DIR, 'globals.css')
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+export const VERSION: string = (() => {
+  try {
+    const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'))
+    return pkg.version || '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+})()
+
+export const WEBVIEW_ENGINE: string = (() => {
+  switch (process.platform) {
+    case 'darwin':
+      return 'WKWebView (macOS)'
+    case 'win32':
+      return 'WebView2 (Windows)'
+    case 'linux':
+      return 'WebKitGTK (Linux)'
+    default:
+      return `OS native (${process.platform})`
+  }
+})()
+
+export const DEFAULT_WIN_TITLE = 'Murasaki App'
+export const DEFAULT_WIN_SIZE = { width: 1280, height: 800 }

package/src/runtime/hmr.ts

@@ -0,0 +1,26 @@
+// File watcher for src/ — debounces multi-event saves and triggers reload.
+
+import { existsSync, watch } from 'node:fs'
+import { printHint } from '../cli/log.ts'
+import { SRC_DIR } from '../env.ts'
+
+export function setupHmr(onChange: (filename: string) => void): void {
+  if (!existsSync(SRC_DIR)) {
+    printHint('src/ directory not found — nothing to watch')
+    return
+  }
+  let debounce: NodeJS.Timeout | null = null
+  let lastFile = ''
+  try {
+    watch(SRC_DIR, { recursive: true }, (_event, filename) => {
+      if (!filename) return
+      if (debounce) clearTimeout(debounce)
+      lastFile = filename.toString()
+      debounce = setTimeout(() => {
+        onChange(lastFile)
+      }, 80)
+    })
+  } catch (e: any) {
+    printHint(`HMR watcher failed: ${e.message}`)
+  }
+}

package/src/runtime/load.ts

@@ -0,0 +1,39 @@
+// Loads the user's src/app.tsx, src/layout.tsx, src/globals.css.
+// Uses cache-busting dynamic import so file edits are picked up
+// without restarting the Node process.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+import { APP_PATH, GLOBALS_CSS, LAYOUT_PATH } from '../env.ts'
+import type { Metadata } from '../index.ts'
+import type { LayoutModule, ReactComponent } from '../types.ts'
+
+async function dynImport(path: string) {
+  const url = pathToFileURL(path).href + `?v=${Date.now()}`
+  return import(url)
+}
+
+export async function loadApp(): Promise<ReactComponent | null> {
+  if (!existsSync(APP_PATH)) return null
+  const mod = await dynImport(APP_PATH)
+  return mod.default as ReactComponent
+}
+
+export async function loadLayout(): Promise<LayoutModule> {
+  if (!existsSync(LAYOUT_PATH)) return null
+  const mod = await dynImport(LAYOUT_PATH)
+  if (!mod.default) return null
+  return {
+    component: mod.default as ReactComponent,
+    metadata: mod.metadata as Metadata | undefined,
+  }
+}
+
+export function loadGlobalsCss(): string {
+  if (!existsSync(GLOBALS_CSS)) return ''
+  try {
+    return readFileSync(GLOBALS_CSS, 'utf8')
+  } catch {
+    return ''
+  }
+}

package/src/runtime/render.tsx

@@ -0,0 +1,55 @@
+// Renders <Layout><App /></Layout> to an HTML string and injects
+// metadata (<title>, <meta description>) + src/globals.css.
+
+import { createElement } from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import type { RenderResult } from '../types.ts'
+import { loadApp, loadGlobalsCss, loadLayout } from './load.ts'
+
+const NO_APP_HTML =
+  '<!doctype html><html><body style="font-family:system-ui;padding:40px;">' +
+  '<h1 style="color:#A855F7">src/app.tsx not found</h1>' +
+  '<p>Create one and the window will reload.</p></body></html>'
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+export async function renderApp(): Promise<RenderResult> {
+  const App = await loadApp()
+  if (!App) return { html: NO_APP_HTML }
+
+  const layoutData = await loadLayout()
+  const metadata = layoutData?.metadata
+  const appEl = createElement(App)
+  const tree = layoutData ? createElement(layoutData.component, null, appEl) : appEl
+  let html = '<!doctype html>' + renderToStaticMarkup(tree)
+
+  const headInjects: string[] = []
+  if (metadata?.title && !/<title>.*?<\/title>/i.test(html)) {
+    headInjects.push(`<title>${escapeHtml(metadata.title)}</title>`)
+  }
+  if (metadata?.description && !/<meta[^>]+name=["']description["']/i.test(html)) {
+    headInjects.push(`<meta name="description" content="${escapeHtml(metadata.description)}">`)
+  }
+
+  const css = loadGlobalsCss()
+  if (css) {
+    headInjects.push(`<style data-murasaki="globals.css">${css}</style>`)
+  }
+
+  if (headInjects.length) {
+    const blob = headInjects.join('')
+    if (html.includes('</head>')) {
+      html = html.replace('</head>', blob + '</head>')
+    } else {
+      html = html.replace('<body', blob + '<body')
+    }
+  }
+
+  return { html, metadata }
+}

package/src/runtime/shortcuts.ts

@@ -0,0 +1,31 @@
+// Terminal keyboard shortcuts (raw mode stdin).
+//
+//   o   open the window
+//   r   restart (close + open)
+//   q   quit
+//   Ctrl+C   quit
+
+export type ShortcutHandlers = {
+  onOpen: () => void
+  onRestart: () => void
+  onQuit: () => void
+}
+
+export function setupShortcuts(handlers: ShortcutHandlers): void {
+  if (!process.stdin.isTTY) return
+  process.stdin.setRawMode(true)
+  process.stdin.resume()
+  process.stdin.setEncoding('utf8')
+  process.stdin.on('data', (key) => {
+    const k = key.toString()
+    if (k === 'o' || k === 'O') handlers.onOpen()
+    else if (k === 'r' || k === 'R') handlers.onRestart()
+    else if (k === 'q' || k === 'Q' || k === '\x03' /* Ctrl+C */) handlers.onQuit()
+  })
+}
+
+export function teardownStdin(): void {
+  try {
+    process.stdin.setRawMode(false)
+  } catch {}
+}

package/src/runtime/window.ts

@@ -0,0 +1,94 @@
+// Owns the Application + BrowserWindow lifecycle.
+//
+// The EventLoop is created exactly once (winit/tao limitation). ControlFlow.Wait
+// keeps the loop alive even when no windows are open, so the user can press
+// `o` in the terminal to re-open the window.
+
+import { Application, ControlFlow } from '@webviewjs/webview'
+import { printClosed, printError, printHint, printReloaded } from '../cli/log.ts'
+import { DEFAULT_WIN_SIZE, DEFAULT_WIN_TITLE, projectRoot } from '../env.ts'
+import type { Metadata } from '../index.ts'
+import type { WindowConfig } from '../types.ts'
+import { renderApp } from './render.tsx'
+
+const config: WindowConfig = {
+  title: DEFAULT_WIN_TITLE,
+  width: DEFAULT_WIN_SIZE.width,
+  height: DEFAULT_WIN_SIZE.height,
+}
+
+export const app = new Application({ controlFlow: ControlFlow.Wait })
+let win: ReturnType<typeof app.createBrowserWindow> | null = null
+let webview: ReturnType<NonNullable<typeof win>['createWebview']> | null = null
+
+app.onEvent((event) => {
+  const kind = event && ((event as any).kind || (event as any).event)
+  if (kind === 'window-close-requested') {
+    // Dispose so the OS close completes — without this the close button hangs.
+    if (win) {
+      try {
+        win.dispose()
+      } catch {}
+    }
+    win = null
+    webview = null
+    printClosed()
+  }
+})
+
+function applyMetadata(metadata?: Metadata) {
+  if (!metadata) return
+  if (metadata.window?.title) config.title = metadata.window.title
+  else if (metadata.title) config.title = metadata.title
+  if (metadata.window?.width) config.width = metadata.window.width
+  if (metadata.window?.height) config.height = metadata.window.height
+}
+
+export function getConfig(): Readonly<WindowConfig> {
+  return config
+}
+
+export async function openWindow(): Promise<void> {
+  if (win) {
+    printHint('Window is already open')
+    return
+  }
+  const { html, metadata } = await renderApp()
+  applyMetadata(metadata)
+  win = app.createBrowserWindow({
+    title: config.title,
+    width: config.width,
+    height: config.height,
+  })
+  webview = win.createWebview({ html })
+}
+
+export function closeWindow(): void {
+  if (!win) return
+  try {
+    win.dispose()
+  } catch {}
+  win = null
+  webview = null
+}
+
+export async function reloadWindow(triggerFile: string): Promise<void> {
+  if (!webview) return
+  try {
+    const { html } = await renderApp()
+    webview.loadHtml(html)
+    printReloaded(triggerFile.replace(projectRoot + '/', ''))
+  } catch (e: any) {
+    printError(`Reload failed: ${e.message}`)
+  }
+}
+
+export function runApp(): void {
+  app.run()
+}
+
+export function exitApp(): void {
+  try {
+    app.exit()
+  } catch {}
+}

package/src/types.ts

@@ -0,0 +1,22 @@
+// Internal shared types (the public Metadata type is re-exported from index.ts).
+
+import type { ComponentType, ReactNode } from 'react'
+import type { Metadata } from './index.ts'
+
+export type ReactComponent = ComponentType<{ children?: ReactNode }>
+
+export type LayoutModule = {
+  component: ReactComponent
+  metadata?: Metadata
+} | null
+
+export type WindowConfig = {
+  title: string
+  width: number
+  height: number
+}
+
+export type RenderResult = {
+  html: string
+  metadata?: Metadata
+}