docs: tweaks

Kikobeats · Kikobeats · commit 405cb0002695 · 2026-05-21T08:43:27.000+02:00
diff --git a/README.md b/README.md
@@ -18,24 +18,29 @@
 
 # Why isolated-function?
 
-Sometimes your application needs to run JavaScript that did not come from your codebase.
+Sometimes your application needs to let users customize a piece of behavior with JavaScript.
 
-That code might come from an AI agent, a customer-defined workflow, a plugin, a webhook transform, or an automation rule. You want the useful part: let people customize behavior with code. You do not want the dangerous part: letting that code read files, spawn processes, install anything it wants, or run forever.
+That code might be a function template for an AI agent, a customer-defined workflow, a plugin, a webhook transform, or an automation rule. You provide the shape of the function and the runtime context; users provide the custom logic. You want the useful part: programmable behavior without turning the rest of your application into the execution environment.
 
-**isolated-function** gives you a small API for running that code in a separate Node.js process with clear limits:
+**isolated-function** gives you a small API for turning user-customizable function templates into controlled executions:
 
-- give it a function
+- give it a function or generated function template
+- pass runtime arguments into it
 - choose what it is allowed to do
 - set memory and timeout limits
 - run it
 - get back the result, logs, errors, and timing data
 
-It is a sandbox for the kind of code you need to execute, but do not fully trust.
+It is useful when your product needs user-defined logic, but you still want a narrow execution contract around what that logic can receive, return, import, and access.
 
 # What it does
 
 At a high level, isolated-function wraps a JavaScript function and runs it away from your main process.
 
+The core use case is giving your product a controlled function template that users can customize. Your application owns the template, runtime arguments, dependencies, permissions, timeout, memory, result shape, logging, and cleanup. Users only customize the part of the function you intentionally expose.
+
+This is the pattern used by [`@browserless/function`](https://github.com/microlinkhq/browserless/tree/master/packages/function): it lets users build functions that can access a Puppeteer `page` and related browser context, then runs those functions through isolated-function.
+
 It can:
 
 - run untrusted code in a separate process
@@ -47,7 +52,15 @@ It can:
 - allow only the packages you explicitly trust
 - return profiling data for compile, spawn, run, and total time
 
-# Install
+# What it is not
+
+isolated-function is not a virtual machine, microVM, container runtime, or hypervisor-based sandbox.
+
+It isolates JavaScript by running it in a separate Node.js process with Node.js permissions and resource limits. That is useful for many plugin, workflow, webhook, and AI-agent use cases, but it is not the same security boundary as KVM, Firecracker, Kata Containers, gVisor, or another VM-backed isolation layer.
+
+If you need to execute hostile multi-tenant code, use isolated-function behind a stronger runtime boundary such as a locked-down container, gVisor, Kata Containers, Firecracker, or another hypervisor-backed execution environment.
+
+# Installation
 
 ```bash
 pnpm add isolated-function
diff --git a/docs/README.md b/docs/README.md
@@ -18,24 +18,29 @@
 
 # Why isolated-function?
 
-Sometimes your application needs to run JavaScript that did not come from your codebase.
+Sometimes your application needs to let users customize a piece of behavior with JavaScript.
 
-That code might come from an AI agent, a customer-defined workflow, a plugin, a webhook transform, or an automation rule. You want the useful part: let people customize behavior with code. You do not want the dangerous part: letting that code read files, spawn processes, install anything it wants, or run forever.
+That code might be a function template for an AI agent, a customer-defined workflow, a plugin, a webhook transform, or an automation rule. You provide the shape of the function and the runtime context; users provide the custom logic. You want the useful part: programmable behavior without turning the rest of your application into the execution environment.
 
-**isolated-function** gives you a small API for running that code in a separate Node.js process with clear limits:
+**isolated-function** gives you a small API for turning user-customizable function templates into controlled executions:
 
-- give it a function
+- give it a function or generated function template
+- pass runtime arguments into it
 - choose what it is allowed to do
 - set memory and timeout limits
 - run it
 - get back the result, logs, errors, and timing data
 
-It is a sandbox for the kind of code you need to execute, but do not fully trust.
+It is useful when your product needs user-defined logic, but you still want a narrow execution contract around what that logic can receive, return, import, and access.
 
 # What it does
 
 At a high level, isolated-function wraps a JavaScript function and runs it away from your main process.
 
+The core use case is giving your product a controlled function template that users can customize. Your application owns the template, runtime arguments, dependencies, permissions, timeout, memory, result shape, logging, and cleanup. Users only customize the part of the function you intentionally expose.
+
+This is the pattern used by [`@browserless/function`](https://github.com/microlinkhq/browserless/tree/master/packages/function): it lets users build functions that can access a Puppeteer `page` and related browser context, then runs those functions through isolated-function.
+
 It can:
 
 - run untrusted code in a separate process
@@ -47,7 +52,15 @@ It can:
 - allow only the packages you explicitly trust
 - return profiling data for compile, spawn, run, and total time
 
-# Install
+# What it is not
+
+isolated-function is not a virtual machine, microVM, container runtime, or hypervisor-based sandbox.
+
+It isolates JavaScript by running it in a separate Node.js process with Node.js permissions and resource limits. That is useful for many plugin, workflow, webhook, and AI-agent use cases, but it is not the same security boundary as KVM, Firecracker, Kata Containers, gVisor, or another VM-backed isolation layer.
+
+If you need to execute hostile multi-tenant code, use isolated-function behind a stronger runtime boundary such as a locked-down container, gVisor, Kata Containers, Firecracker, or another hypervisor-backed execution environment.
+
+# Installation
 
 ```bash
 pnpm add isolated-function
diff --git a/docs/src/css/style.css b/docs/src/css/style.css
@@ -93,7 +93,10 @@ body:not(.sticky) .sidebar {
   background: var(--line);
 }
 
-.sidebar-toggle,
+.sidebar-toggle {
+  display: none;
+}
+
 .badge,
 img[src*='shields.io'],
 .site-header {
@@ -592,23 +595,79 @@ section.cover {
     display: none;
   }
 
+  body {
+    overflow-x: hidden;
+  }
+
   body:not(.sticky) .sidebar {
-    display: none;
+    opacity: 1;
+    pointer-events: auto;
+    visibility: visible;
+    transform: none;
   }
 
   .sidebar {
-    position: static;
+    position: fixed;
+    top: 0;
+    left: calc(-1 * (var(--sidebar-width) + 30px));
+    width: var(--sidebar-width);
+    height: 100vh;
+    height: 100dvh;
+    z-index: 3;
+    border-right: 1px solid var(--line);
+    border-bottom: 0;
+    padding-top: 62px;
+    transition: transform 0.25s ease-out;
+  }
+
+  .sidebar-toggle {
+    cursor: pointer;
+    display: inherit;
+    border: 0;
+    outline: none;
+    padding: 0 10px;
+    left: 6px;
+    transition: opacity 0.3s;
+    z-index: 4;
+    position: fixed;
+    top: 0;
+    height: 62px;
     width: 100%;
-    height: auto;
-    border-right: 0;
-    border-bottom: 1px solid var(--line);
-    opacity: 1;
-    transform: none;
+    background: var(--bg);
+  }
+
+  .sidebar-toggle:focus-visible {
+    outline: 2px solid var(--active);
+    outline-offset: 2px;
+  }
+
+  .sidebar-toggle span {
+    background-color: var(--text);
+    display: block;
+    margin-bottom: 5px;
+    width: 24px;
+    height: 3px;
+  }
+
+  body.sidebar-toggle {
+    display: none;
+  }
+
+  body.close .sidebar,
+  body.close .content {
+    transform: translateX(calc(var(--sidebar-width) + 30px));
+  }
+
+  body.close .sidebar-toggle {
+    background: var(--bg);
+    transition: background-color 0.3s;
+    width: calc(var(--sidebar-width) + 34px);
   }
 
   .content {
-    margin-left: 0;
-    padding: 20px 12px 40px;
+    margin: 0;
+    padding: 62px 12px 40px;
+    transition: transform 0.25s ease;
   }
 
   .markdown-section h1,
diff --git a/docs/src/js/main.js b/docs/src/js/main.js
@@ -79,6 +79,8 @@ const setupSidebarHighlight = () => {
 
     const id = parseSectionId(link.getAttribute('href'))
     if (id) setActiveLink(links, id)
+
+    if (window.innerWidth <= 900) document.body.classList.remove('close')
   }
 
   window.addEventListener('scroll', requestSync, { passive: true })
diff --git a/docs/static/main.min.js b/docs/static/main.min.js
diff --git a/docs/static/style.min.css b/docs/static/style.min.css

Original file line number	Diff line number	Diff line change
`@@ -79,6 +79,8 @@ const setupSidebarHighlight = () => {`
`79`	`79`
`80`	`80`	`const id = parseSectionId(link.getAttribute('href'))`
`81`	`81`	`if (id) setActiveLink(links, id)`
	`82`	`+`
	`83`	`+ if (window.innerWidth <= 900) document.body.classList.remove('close')`
`82`	`84`	`}`
`83`	`85`
`84`	`86`	`window.addEventListener('scroll', requestSync, { passive: true })`