@jseeio/jsee 0.4.1 → 0.8.0

package/src/cli.js

@@ -4,23 +4,27 @@ const os = require('os')
 const crypto = require('crypto')
 
 const minimist = require('minimist')
-const jsdoc2md = require('jsdoc-to-markdown')
-const showdown = require('showdown')
-const showdownKatex = require('showdown-katex')
-const converter = new showdown.Converter({
-  extensions: [
-    showdownKatex({
-      throwOnError: true,
-      displayMode: true,
-      errorColor: '#1500ff',
-      output: 'mathml'
-    }),
-  ],
-  tables: true
-})
-showdown.setFlavor('github')
-
-const { getModelFuncJS, sanitizeName } = require('./utils.js')
+
+const { getModelFuncJS, sanitizeName, generateOpenAPISpec, serializeResult, parseMultipart, fileExtToOutputType } = require('./utils.js')
+
+let jsdoc2md
+function getJsdocToMarkdown () {
+  if (!jsdoc2md) jsdoc2md = require('jsdoc-to-markdown')
+  return jsdoc2md
+}
+
+let markdownConverter
+function getMarkdownConverter () {
+  if (markdownConverter) return markdownConverter
+
+  const MarkdownIt = require('markdown-it')
+  markdownConverter = new MarkdownIt({
+    html: true,
+    linkify: true,
+    typographer: false
+  })
+  return markdownConverter
+}
 
 // left padding of multiple lines
 function pad (str, len, start=0) {
@@ -36,6 +40,95 @@ function toArray (value) {
   return Array.isArray(value) ? value : [value]
 }
 
+// Auto-detect CLI argument type: file path, number, JSON array/object, or string
+function detectArgValue (value) {
+  if (typeof value === 'number') return value
+  if (typeof value === 'boolean') return value
+  if (typeof value !== 'string') return value
+  // File on disk
+  if (fs.existsSync(value) && fs.statSync(value).isFile()) return value
+  // Number
+  if (value !== '' && !isNaN(value)) return Number(value)
+  // JSON array or object
+  if (value.startsWith('[') || value.startsWith('{')) {
+    try { return JSON.parse(value) } catch (e) { /* not JSON */ }
+  }
+  return value
+}
+
+function readDirListing (resolved, relative) {
+  const entries = fs.readdirSync(resolved, { withFileTypes: true })
+  return entries
+    .filter(e => e.isFile() && !e.name.startsWith('.'))
+    .map(e => ({
+      name: e.name,
+      path: path.posix.join(relative, e.name),
+      size: fs.statSync(path.join(resolved, e.name)).size,
+      type: fileExtToOutputType(e.name),
+      selected: true
+    }))
+}
+
+function generateIdentitySchema (target, cwd) {
+  const resolved = path.isAbsolute(target) ? target : path.join(cwd, target)
+  const stat = fs.existsSync(resolved) ? fs.statSync(resolved) : null
+
+  if (stat && stat.isDirectory()) {
+    const files = readDirListing(resolved, target)
+    // Pre-select the first file
+    files.forEach((f, i) => { f.selected = i === 0 })
+    return {
+      schema: {
+        model: {
+          name: 'identity',
+          type: 'function',
+          worker: false,
+          autorun: true,
+          code: `function identity(inputs) {
+  var files = inputs.files || []
+  var selected = files.filter(function (f) { return f.selected })
+  var stats = { files: inputs.files ? inputs.files.length : 0, totalSize: (inputs.files || []).reduce(function (s, f) { return s + (f.size || 0) }, 0), types: {} }
+  ;(inputs.files || []).forEach(function (f) { var t = f.type || 'unknown'; stats.types[t] = (stats.types[t] || 0) + 1 })
+  return { stats: stats, viewer: selected.length > 0 ? '/__jsee/file?path=' + encodeURIComponent(selected[0].path) : null }
+}`
+        },
+        inputs: [{
+          name: 'files',
+          type: 'folder',
+          default: files,
+          disabled: true,
+          reactive: true,
+          select: 'one'
+        }],
+        outputs: [
+          { name: 'stats', type: 'object' },
+          { name: 'viewer', type: 'viewer' }
+        ],
+        autorun: true
+      },
+      identity: true,
+      serveDir: resolved
+    }
+  }
+
+  if (stat && stat.isFile()) {
+    const ext = path.extname(target).toLowerCase()
+    if (ext === '.json' || ext === '.js') return null
+    const outputType = fileExtToOutputType(target)
+    return {
+      schema: {
+        inputs: [],
+        outputs: [{ name: path.basename(target), type: outputType }],
+        autorun: true
+      },
+      identity: true,
+      serveFile: { path: target, resolved }
+    }
+  }
+
+  return null
+}
+
 function collectFetchBundleBlocks (schema) {
   return []
     .concat(toArray(schema.model))
@@ -166,14 +259,32 @@ function resolveOutputPath (cwd, outputPath) {
   return path.join(cwd, outputPath)
 }
 
-async function loadRuntimeCode (version) {
-  if (version === 'dev') {
-    return fs.readFileSync(path.join(__dirname, '..', 'dist', 'jsee.js'), 'utf8')
-  }
-  if (version === 'latest') {
-    return fs.readFileSync(path.join(__dirname, '..', 'dist', 'jsee.runtime.js'), 'utf8')
+const FULL_BUNDLE_TYPES = ['chart', '3d', 'map']
+
+function needsFullBundle (schema) {
+  const outputs = schema.outputs || []
+  const check = (list) => list.some(o => {
+    if (FULL_BUNDLE_TYPES.includes(o.type)) return true
+    if (o.type === 'group' && o.elements) return check(o.elements)
+    return false
+  })
+  return check(outputs)
+}
+
+function getBundleFilename (schema) {
+  return needsFullBundle(schema) ? 'jsee.full.js' : 'jsee.core.js'
+}
+
+async function loadRuntimeCode (version, schema) {
+  const bundle = schema ? getBundleFilename(schema) : 'jsee.core.js'
+  if (version === 'dev' || version === 'latest') {
+    const filePath = path.join(__dirname, '..', 'dist', bundle)
+    if (fs.existsSync(filePath)) {
+      return fs.readFileSync(filePath, 'utf8')
+    }
+    return fs.readFileSync(path.join(__dirname, '..', 'dist', 'jsee.core.js'), 'utf8')
   }
-  const response = await fetch(`https://cdn.jsdelivr.net/npm/@jseeio/jsee@${version}/dist/jsee.runtime.js`)
+  const response = await fetch(`https://cdn.jsdelivr.net/npm/@jseeio/jsee@${version}/dist/${bundle}`)
   return response.text()
 }
 
@@ -182,7 +293,6 @@ function getDataFromArgv (schema, argv, loadFiles=true) {
   if (schema.inputs) {
     schema.inputs.forEach(inp => {
       const inputName = sanitizeName(inp.name)
-      console.log('Processing input:', inp.name, 'as', inputName)
       if (inputName in argv) {
         switch (inp.type) {
           case 'file':
@@ -197,6 +307,17 @@ function getDataFromArgv (schema, argv, loadFiles=true) {
               process.exit(1)
             }
             break
+          case 'folder':
+            if (!loadFiles) {
+              data[inp.name] = argv[inputName]
+              break
+            }
+            const dirPath = argv[inputName]
+            const resolved = path.isAbsolute(dirPath) ? dirPath : path.join(process.cwd(), dirPath)
+            if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+              data[inp.name] = readDirListing(resolved, dirPath)
+            }
+            break
           case 'int':
             data[inp.name] = parseInt(argv[inputName], 10)
             break
@@ -393,9 +514,9 @@ function template(schema, blocks) {
   } else if (schema.page && schema.page.title) {
     title = schema.page.title
   } else if (schema.model) {
-    if (Array.isArray(schema.model)) {
+    if (Array.isArray(schema.model) && schema.model.length > 0) {
       title = schema.model[0].name
-    } else {
+    } else if (!Array.isArray(schema.model)) {
       title = schema.model.name
     }
   }
@@ -538,8 +659,7 @@ function template(schema, blocks) {
     @media screen and (min-width: 800px) { .one-half { width: calc(50% - (30px / 2)); } }
     /** Jsee elements */
     .app-container { background-color: #F0F1F4; border-bottom: 1px solid #e8e8e8; padding-bottom: 55px }
-    #download-btn { float: right; margin-top: 10px; padding: 10px; background-color: white; border: none; cursor: pointer; }
-    #download-btn:hover { background-color: #f0f0f0; }
+    #save-html-btn:hover { background-color: #f0f0f0 !important; }
     .schema-description { background-color: #f8f8fa; padding: 20px; margin-top: 20px; border-radius: 10px; border: 1px solid #e8e8e8; }
     .schema-description h2, .schema-description h3, .schema-description h4 { margin-top: 10px; }
     /** Logos */
@@ -554,10 +674,10 @@ function template(schema, blocks) {
 </head>
 <body>
   ${blocks.hiddenElementHtml}
+  ${blocks.serveBarHtml}
   <header class="site-header">
     <div class="wrapper">
       <span class="site-title">${title}</span>
-      <button id="download-btn" title="Download bundled HTML file without external dependencies to use offline">Download bundle (html)</button>
     </div>
   </header>
   <div class="page-content app-container">
@@ -593,15 +713,25 @@ function template(schema, blocks) {
   </footer>
   ${blocks.jseeHtml}
   <script>
-    const schema = ${JSON.stringify(schema, null, 2)}
-    const title = "${title}"
+    ${blocks.schemaScript}
+    var currentSchema = schemaServer || schemaClient
+    var container = document.getElementById('jsee-container')
     var env = new JSEE({
-      container: document.getElementById('jsee-container'),
-      schema
-    })
-    document.getElementById('download-btn').addEventListener('click', async () => {
-      env.download(title)
+      container: container,
+      schema: currentSchema
     })
+    var toggle = document.getElementById('exec-toggle')
+    if (toggle) {
+      toggle.addEventListener('change', function () {
+        env.destroy()
+        currentSchema = this.checked ? schemaClient : schemaServer
+        env = new JSEE({ container: container, schema: currentSchema })
+      })
+    }
+    var saveBtn = document.getElementById('save-html-btn')
+    if (saveBtn) {
+      saveBtn.addEventListener('click', function () { env.download("${title}") })
+    }
   </script>
 </body>
 </html>`
@@ -625,7 +755,7 @@ async function gen (pargv, returnHtml=false) {
     runtime: 'r',
   }
   const argvDefault = {
-    execute: false, // execute the model code on the server
+    execute: 'auto', // execute the model code on the server (auto = server-side when serving local .js models)
     fetch: false, // fetch the JSEE runtime from the CDN or local server
     inputs: 'schema.json', // default input is schema.json in the current working directory
     port: 3000, // default port for the server
@@ -637,12 +767,150 @@ async function gen (pargv, returnHtml=false) {
   let argv = minimist(pargv, {
     alias: argvAlias,
     default: argvDefault,
-    boolean: ['help', 'h'],
+    boolean: ['help', 'h', 'html', 'client'],
   })
 
+  // ── jsee init <template> ──────────────────────────────────────────
+  if (argv._[0] === 'init') {
+    const tpl = argv._[1] || 'minimal'
+    const cwd = process.cwd()
+
+    if (argv.html) {
+      // Single index.html with inline schema + CDN script
+      const dest = path.join(cwd, 'index.html')
+      if (fs.existsSync(dest)) {
+        console.log('index.html already exists, skipping')
+        return
+      }
+      let htmlContent
+      if (tpl === 'chat') {
+        htmlContent = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Chat</title>
+</head>
+<body>
+  <div id="jsee-container"></div>
+  <script src="https://cdn.jsdelivr.net/npm/@jseeio/jsee@latest/dist/jsee.core.js"></script>
+  <script>
+    new JSEE({
+      container: document.getElementById('jsee-container'),
+      schema: {
+        model: { code: function chat(message, history) { return { chat: 'You said: ' + message } }, worker: false },
+        inputs: [{ name: 'message', type: 'string', enter: true }],
+        outputs: [{ name: 'chat', type: 'chat' }]
+      }
+    })
+  </script>
+</body>
+</html>`
+      } else {
+        htmlContent = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>My App</title>
+</head>
+<body>
+  <div id="jsee-container"></div>
+  <script src="https://cdn.jsdelivr.net/npm/@jseeio/jsee@latest/dist/jsee.core.js"></script>
+  <script>
+    new JSEE({
+      container: document.getElementById('jsee-container'),
+      schema: {
+        model: { code: function greet(name, count) { return { greeting: (name + '\\n').repeat(count) } }, worker: false },
+        inputs: [
+          { name: 'name', type: 'string', default: 'World' },
+          { name: 'count', type: 'slider', min: 1, max: 10, default: 3 }
+        ],
+        outputs: [{ name: 'greeting', type: 'code' }]
+      }
+    })
+  </script>
+</body>
+</html>`
+      }
+      fs.writeFileSync(dest, htmlContent)
+      console.log('Created index.html')
+      return
+    }
+
+    // Multi-file scaffolding
+    const files = {}
+    if (tpl === 'chat') {
+      files['schema.json'] = JSON.stringify({
+        model: { url: 'model.js', name: 'chat', worker: false },
+        inputs: [{ name: 'message', type: 'string', enter: true }],
+        outputs: [{ name: 'chat', type: 'chat' }]
+      }, null, 2) + '\n'
+      files['model.js'] = `function chat(message, history) {
+  return { chat: 'You said: ' + message }
+}
+`
+      files['README.md'] = `# Chat
+
+A chat app built with [JSEE](https://jsee.org).
+
+## Run
+
+\`\`\`bash
+npx @jseeio/jsee schema.json
+\`\`\`
+`
+    } else {
+      // minimal (default)
+      files['schema.json'] = JSON.stringify({
+        model: { url: 'model.js', name: 'greet' },
+        inputs: [
+          { name: 'name', type: 'string', default: 'World' },
+          { name: 'count', type: 'slider', min: 1, max: 10, default: 3 }
+        ],
+        outputs: [{ name: 'greeting', type: 'code' }]
+      }, null, 2) + '\n'
+      files['model.js'] = `function greet(name, count) {
+  return { greeting: (name + '\\n').repeat(count) }
+}
+`
+      files['README.md'] = `# My App
+
+A web app built with [JSEE](https://jsee.org).
+
+## Run
+
+\`\`\`bash
+npx @jseeio/jsee schema.json
+\`\`\`
+`
+    }
+
+    let created = 0
+    for (const [filename, content] of Object.entries(files)) {
+      const dest = path.join(cwd, filename)
+      if (fs.existsSync(dest)) {
+        console.log(`${filename} already exists, skipping`)
+      } else {
+        fs.writeFileSync(dest, content)
+        console.log(`Created ${filename}`)
+        created++
+      }
+    }
+    if (created === 0) {
+      console.log('All files already exist, nothing to do')
+    }
+    return
+  }
+
   if (argv.help || argv.h) {
     console.log(`
-Usage: jsee [schema.json] [options]
+Usage: jsee [schema.json] [data...] [options]
+       jsee init [template] [--html]
+
+Commands:
+  init [template]           Scaffold a new JSEE project (templates: minimal, chat)
+    --html                  Generate a single index.html instead of separate files
 
 Options:
   -i, --inputs <file>       Input schema file (default: schema.json)
@@ -651,24 +919,45 @@ Options:
   -p, --port <number>       Dev server port (default: 3000)
   -v, --version <version>   JSEE runtime version (default: latest)
   -f, --fetch               Fetch and bundle runtime + dependencies into output
-  -e, --execute             Execute model server-side
+  -e, --execute             Execute model server-side (auto-enabled when serving local .js models)
+      --client              Force client-side execution (disable auto server-side)
   -c, --cdn <url|bool>      Rewrite model URLs for CDN deployment
   -r, --runtime <mode>      Runtime: auto|local|cdn|inline or a custom URL/path (default: auto)
       --verbose             Enable verbose logging
 
+Data inputs:
+  Positional args after the schema file are mapped to schema inputs in order.
+  Named args (--name=value) are matched to schema inputs by name.
+  Values are auto-detected: numbers, JSON arrays/objects, file paths, or strings.
+  Inputs set from the CLI are locked (non-editable) in the GUI.
+
 Examples:
+  jsee init                         Scaffold minimal project (schema.json + model.js)
+  jsee init chat                    Scaffold chat project
+  jsee init --html                  Generate single index.html
   jsee schema.json                  Start dev server with schema
+  jsee schema.json 42 hello         Pass positional data to first two inputs
+  jsee schema.json --a=100 --b=200  Pass named data inputs
+  jsee schema.json data.csv         Pass a file path as input
   jsee schema.json -o app.html      Generate static HTML file
   jsee schema.json -o app.html -f   Generate self-contained HTML with bundled runtime
   jsee -p 8080                      Start dev server on port 8080
+  jsee report.pdf                   Serve a PDF file (auto-detected viewer)
+  jsee data/                        Serve a folder (file browser with preview)
 
 Documentation: https://jsee.org
     `.trim())
     return
   }
 
-  // Set argv.inputs to the first non-option argument if it exists
-  if (!imported && argv._.length > 0 && !argv.inputs) {
+  // Check if first positional arg is a file or directory for identity serving
+  let identityResult = null
+  if (!imported && argv._.length > 0) {
+    identityResult = generateIdentitySchema(argv._[0], process.cwd())
+  }
+
+  // Set argv.inputs to the first positional argument if it looks like a schema/script
+  if (!identityResult && !imported && argv._.length > 0 && argv.inputs === argvDefault.inputs) {
     argv.inputs = argv._[0]
   }
 
@@ -709,7 +998,20 @@ Documentation: https://jsee.org
     outputs = outputs.split(',')
   }
 
-  if (inputs.length === 0) {
+  if (identityResult) {
+    schema = identityResult.schema
+    schemaPath = null
+    log('Identity mode:', identityResult.serveFile ? 'file' : 'folder')
+    if (identityResult.serveFile) {
+      const outputType = schema.outputs[0].type
+      const textTypes = ['table', 'markdown', 'html', 'object', 'code']
+      if (textTypes.includes(outputType)) {
+        schema.outputs[0].value = fs.readFileSync(identityResult.serveFile.resolved, 'utf8')
+      } else {
+        schema.outputs[0].value = identityResult.serveFile.path
+      }
+    }
+  } else if (inputs.length === 0) {
     console.error('No inputs provided')
     process.exit(1)
   } else if ((inputs.length === 1) && (inputs[0].includes('.json'))) {
@@ -722,7 +1024,7 @@ Documentation: https://jsee.org
   } else {
     // Array of js files
     // Generate schema
-    let jsdocData = jsdoc2md.getTemplateDataSync({ files: inputs.map(f => path.join(cwd, f)) })
+    let jsdocData = getJsdocToMarkdown().getTemplateDataSync({ files: inputs.map(f => path.join(cwd, f)) })
     schema = genSchema(jsdocData)
     // jsdocMarkdown = jsdoc2md.renderSync({
     //   data: jsdocData,
@@ -740,10 +1042,15 @@ Documentation: https://jsee.org
         if (inp.alias) {
           argvAlias[inputName] = inp.alias
         }
-        // Use positional arguments as schema inputs defaults if JSEE CLI is imported
+        // Use positional arguments as schema input defaults
         if (imported && argv._.length > inp_index) {
           log('Using positional argument for input:', inputName, argv._[inp_index])
-          argvDefault[inputName] = argv._[inp_index]
+          argvDefault[inputName] = detectArgValue(argv._[inp_index])
+        } else if (!imported && argv._.length > inp_index + 1) {
+          // Skip first positional arg (schema file), map rest to inputs
+          const val = argv._[inp_index + 1]
+          log('Using positional argument for input:', inputName, val)
+          argvDefault[inputName] = detectArgValue(val)
         }
         // We don't need to duplicate defaults here, as we handle them on the frontend
         // else if (inp.default) {
@@ -786,19 +1093,49 @@ Documentation: https://jsee.org
     schema.model = [schema.model]
   }
 
+  // Resolve server-side execution mode
+  const hasOutputs = Array.isArray(outputs) ? outputs.length > 0 : Boolean(outputs)
+  let shouldExecute = argv.execute
+  if (shouldExecute === 'auto') {
+    const isServing = !hasOutputs
+    if (argv.client) {
+      shouldExecute = false
+    } else if (isServing) {
+      shouldExecute = schema.model.every(m =>
+        m.url && m.url.endsWith('.js') && !isHttpUrl(m.url))
+    } else {
+      shouldExecute = false
+    }
+  } else {
+    shouldExecute = Boolean(shouldExecute)
+  }
+
+  // Store original models before execute/CDN mutations (for client-side toggle)
+  const originalModels = JSON.parse(JSON.stringify(schema.model))
+
   // Server-side execution
-  // If execute is true, we will prepare the model functions to run on the server side
+  // Prepare the model functions to run on the server side
   // Schema model will be updated with the server url and POST method
-  if (argv.execute) {
+  if (shouldExecute) {
     await Promise.all(schema.model.map(async m => {
       log('Preparing a model to run on the server side:', m.name, m.url)
-      const target = require(path.join(schemaPath ? path.dirname(schemaPath) : cwd, m.url))
+      const modelPath = path.join(schemaPath ? path.dirname(schemaPath) : cwd, m.url)
+      let target = require(modelPath)
+      // Handle browser-style model files (no module.exports) — eval the source
+      // to extract the named function, similar to how the worker does it
+      if (typeof target !== 'function' && (!target || Object.keys(target).length === 0)) {
+        const src = fs.readFileSync(modelPath, 'utf-8')
+        const fn = new Function(src + `\nreturn typeof ${m.name} === 'function' ? ${m.name} : undefined`)()
+        if (typeof fn === 'function') {
+          target = fn
+        }
+      }
       modelFuncs[m.name] = await getModelFuncJS(m, target, {log})
       m.type = 'post'
       m.url = `/${m.name}`
       m.worker = false
     }))
-  } 
+  }
   
   // Switch to CDN for model files
   if (argv.cdn) {
@@ -838,7 +1175,7 @@ Documentation: https://jsee.org
   // Generate description block
   if (description) {
     const descriptionMd = fs.readFileSync(path.join(cwd, description), 'utf8')
-    descriptionHtml = converter.makeHtml(descriptionMd)
+    descriptionHtml = getMarkdownConverter().render(descriptionMd)
 
     if (descriptionMd.includes('---')) {
       descriptionTxt = descriptionMd
@@ -855,11 +1192,10 @@ Documentation: https://jsee.org
   // Generate jsee code
   let jseeHtml = ''
   let hiddenElementHtml = ''
-  const hasOutputs = Array.isArray(outputs) ? outputs.length > 0 : Boolean(outputs)
   const runtimeMode = resolveRuntimeMode(argv.runtime, argv.fetch, hasOutputs)
   if (argv.fetch) {
     // Fetch jsee code from the CDN or local server
-    const jseeCode = await loadRuntimeCode(argv.version)
+    const jseeCode = await loadRuntimeCode(argv.version, schema)
     jseeHtml = `<script>${jseeCode}</script>`
     // Fetch model files and store them in hidden elements
     hiddenElementHtml += '<div id="hidden-storage" style="display: none;">'
@@ -933,14 +1269,14 @@ Documentation: https://jsee.org
     hiddenElementHtml += '</div>'
   } else {
     if (runtimeMode === 'inline') {
-      const jseeCode = await loadRuntimeCode(argv.version)
+      const jseeCode = await loadRuntimeCode(argv.version, schema)
       jseeHtml = `<script>${jseeCode}</script>`
     } else if (runtimeMode === 'cdn') {
-      jseeHtml = `<script src="https://cdn.jsdelivr.net/npm/@jseeio/jsee@${argv.version}/dist/jsee.runtime.js"></script>`
+      const bundle = getBundleFilename(schema)
+      jseeHtml = `<script src="https://cdn.jsdelivr.net/npm/@jseeio/jsee@${argv.version}/dist/${bundle}"></script>`
     } else if (runtimeMode === 'local') {
-      jseeHtml = argv.version === 'dev'
-        ? `<script src="http://localhost:${argv.port}/dist/jsee.js"></script>`
-        : `<script src="http://localhost:${argv.port}/dist/jsee.runtime.js"></script>`
+      const bundle = getBundleFilename(schema)
+      jseeHtml = `<script src="http://localhost:${argv.port}/dist/${bundle}"></script>`
     } else {
       // Custom path/URL passed via --runtime (e.g. ./node_modules/.../jsee.js)
       jseeHtml = `<script src="${runtimeMode}"></script>`
@@ -1004,6 +1340,29 @@ Documentation: https://jsee.org
 
   }
 
+  // Build serve bar (only when serving, not for -o output)
+  let serveBarHtml = ''
+  let schemaScript = ''
+  const isServing = !hasOutputs
+  if (isServing) {
+    const toggleHtml = shouldExecute
+      ? '<label style="cursor:pointer"><input type="checkbox" id="exec-toggle" style="margin-right:4px">Browser</label>'
+      : ''
+    serveBarHtml = `<div id="jsee-serve-bar" style="background:#f8f8f8;border-bottom:1px solid #e0e0e0;padding:6px 15px;font-size:13px;color:#828282;display:flex;align-items:center;gap:16px">
+      <span style="font-family:monospace">localhost:${argv.port}</span>
+      <span style="flex:1"></span>
+      ${toggleHtml}
+      <button id="save-html-btn" style="background:none;border:1px solid #ddd;border-radius:3px;padding:3px 10px;font-size:12px;color:#555;cursor:pointer" title="Save as self-contained HTML file">Save HTML</button>
+    </div>`
+  }
+  if (shouldExecute) {
+    const clientSchema = JSON.parse(JSON.stringify(schema))
+    clientSchema.model = originalModels
+    schemaScript = `var schemaServer = ${JSON.stringify(schema, null, 2)}\n    var schemaClient = ${JSON.stringify(clientSchema, null, 2)}`
+  } else {
+    schemaScript = `var schemaServer = ${JSON.stringify(schema, null, 2)}\n    var schemaClient = null`
+  }
+
   const html = template(schema, {
     descriptionHtml: pad(descriptionHtml, 8, 1),
     descriptionTxt: descriptionTxt,
@@ -1012,6 +1371,8 @@ Documentation: https://jsee.org
     hiddenElementHtml: hiddenElementHtml,
     socialHtml: pad(socialHtml, 2, 1),
     orgHtml: pad(orgHtml, 2, 1),
+    serveBarHtml: serveBarHtml,
+    schemaScript: schemaScript,
   })
 
   if (returnHtml) {
@@ -1037,30 +1398,78 @@ Documentation: https://jsee.org
     const express = require('express')
     const app = express()
     app.use(express.json())
-    if (argv.execute) {
+    app.use(express.raw({ type: 'multipart/form-data', limit: '50mb' }))
+    // CORS
+    app.use((req, res, next) => {
+      res.header('Access-Control-Allow-Origin', '*')
+      res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
+      res.header('Access-Control-Allow-Headers', 'Content-Type')
+      if (req.method === 'OPTIONS') return res.sendStatus(204)
+      next()
+    })
+    // API discovery
+    app.get('/api', (req, res) => {
+      const models = schema.model.map(m => ({
+        name: m.name,
+        endpoint: m.url || '/' + m.name,
+        method: 'POST'
+      }))
+      res.json({ schema, models })
+    })
+    // OpenAPI spec
+    app.get('/api/openapi.json', (req, res) => {
+      res.json(generateOpenAPISpec(schema))
+    })
+    if (shouldExecute) {
       // Create post endpoint for executing the model
       schema.model.forEach(m => {
-        app.post(m.url, (req, res) => {
+        app.post(m.url, async (req, res) => {
           log(`Executing model: ${m.name}`)
           if (m.name in modelFuncs) {
             const modelFunc = modelFuncs[m.name]
             try {
               const dataFromArgv = getDataFromArgv(schema, argv)
-              const dataFromGUI = req.body
+              const contentType = req.headers['content-type'] || ''
+              let dataFromGUI = req.body
+              if (contentType.includes('multipart/form-data') && Buffer.isBuffer(req.body)) {
+                dataFromGUI = parseMultipart(contentType, req.body)
+              }
               const data = { ...dataFromGUI, ...dataFromArgv }
               log('Data for model execution:', data)
-              const result = modelFunc(data)
-              res.json(result)
+              const result = await modelFunc(data)
+              res.json(serializeResult(result))
               log(`Model ${m.name} executed successfully: `, result)
             } catch (error) {
               console.error('Error executing model:', error)
               res.status(500).json({ error: error.message })
             }
+          } else {
+            res.status(404).json({ error: 'Unknown model: ' + m.name })
           }
         })
         log('Model execution endpoints created:', m.url)
       })
     }
+    // Serve folder file listing as JSON
+    app.get('/__jsee/folder', (req, res) => {
+      const dirPath = req.query.path
+      if (!dirPath) return res.status(400).json({ error: 'path required' })
+      const resolved = path.resolve(schemaPath ? path.dirname(schemaPath) : cwd, dirPath)
+      if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+        return res.status(404).json({ error: 'directory not found' })
+      }
+      res.json(readDirListing(resolved, dirPath))
+    })
+    // Serve individual files for viewer output
+    app.get('/__jsee/file', (req, res) => {
+      const filePath = req.query.path
+      if (!filePath) return res.status(400).json({ error: 'path required' })
+      const resolved = path.resolve(schemaPath ? path.dirname(schemaPath) : cwd, filePath)
+      if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
+        return res.status(404).json({ error: 'file not found' })
+      }
+      res.sendFile(resolved)
+    })
     app.get('/', async (req, res) => {
       log('Serving index.html')
       res.send(await gen(pargv, true))
@@ -1089,3 +1498,4 @@ module.exports.resolveLocalImportFile = resolveLocalImportFile
 module.exports.resolveFetchImport = resolveFetchImport
 module.exports.resolveRuntimeMode = resolveRuntimeMode
 module.exports.resolveOutputPath = resolveOutputPath
+module.exports.needsFullBundle = needsFullBundle