{"_id":"@clipra/lumina-sandbox","name":"@clipra/lumina-sandbox","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@clipra/lumina-sandbox","version":"0.1.0","description":"Frontend sandbox SDK for HTML/CSS/JS, GSAP, and Three.js. Built for AI agent harnesses. No model, no Node, no backend.","type":"module","sideEffects":false,"license":"MIT","main":"./src/index.ts","types":"./src/index.ts","exports":{".":"./src/index.ts","./react":"./src/react/index.ts","./html2canvas.min.js":"./assets/html2canvas.min.js"},"scripts":{"test":"node --experimental-strip-types --import ./scripts/register.mjs --test src/sandbox.test.ts","prepublishOnly":"node --experimental-strip-types --import ./scripts/register.mjs --test src/sandbox.test.ts"},"keywords":["sandbox","iframe","agent","harness","html","gsap","three","nextjs","frontend-sandbox","lumina"],"publishConfig":{"access":"public"},"peerDependencies":{"react":">=18","react-dom":">=18"},"peerDependenciesMeta":{"react":{"optional":true},"react-dom":{"optional":true}},"_id":"@clipra/lumina-sandbox@0.1.0","gitHead":"f6e6a09475d7503afd693195348045d94edbebdf","_nodeVersion":"23.1.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-THQ9k0UYY9gZpvDefrZYcUzRMCHLAZz5xlV7EWsonw7sg2AsftaTHFmJcXygZM0U9fGYB2Eh3ZQ+u0Lod0OsjQ==","shasum":"1bbe2be2bc8e194eb47b9eafc83b450137090c0b","tarball":"https://registry.npmjs.org/@clipra/lumina-sandbox/-/lumina-sandbox-0.1.0.tgz","fileCount":28,"unpackedSize":323324,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBHCMDCvbuxv796jYJC0amzqPhOzwQ0Hd1RYjAD4HgSHAiEA6ALl2EYhoRZkptV4YlgUwJEF2I++jdSUvhvTduz+0Tk="}]},"_npmUser":{"name":"thecertifiedcoder","email":"akoredekurline@gmail.com"},"directories":{},"maintainers":[{"name":"thecertifiedcoder","email":"akoredekurline@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/lumina-sandbox_0.1.0_1787692289113_0.9765921767025851"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-25T21:11:28.833Z","0.1.0":"2026-08-25T21:11:29.262Z","modified":"2026-08-25T21:11:29.489Z"},"maintainers":[{"name":"thecertifiedcoder","email":"akoredekurline@gmail.com"}],"description":"Frontend sandbox SDK for HTML/CSS/JS, GSAP, and Three.js. Built for AI agent harnesses. No model, no Node, no backend.","keywords":["sandbox","iframe","agent","harness","html","gsap","three","nextjs","frontend-sandbox","lumina"],"license":"MIT","readme":"# @clipra/lumina-sandbox\n\nFrontend sandbox SDK for **HTML, CSS, JavaScript, GSAP, Three.js, canvas**.  \nBuilt so an **AI agent harness** can create a sandbox, call tools, and render a live iframe preview.\n\nThere is **no model** in this package. You bring the LLM. Lumina is the sandbox + the tool contract.\n\n> **Name:** this package is `@clipra/lumina-sandbox`.\n> `lumina-sandbox` on npm is a **different product** (a backend lifecycle SDK by another author). Do not install that one.\n\nNot for Node, backends, or Linux. That is [Vercel Sandbox](https://vercel.com/docs/sandbox). Lumina is the browser.\n\n**If you are an AI integrating this:** read [`AGENTS.md`](./AGENTS.md) first.\n\n\n```ts\nimport { Sandbox, createHarness } from \"@clipra/lumina-sandbox\";\n\nconst sandbox = Sandbox.create({ template: \"kinetic\" });\nsandbox.writeFile(\"main.js\", `import { gsap } from \"gsap\";\ngsap.to(\"h1\", { y: 40, duration: 1.2, yoyo: true, repeat: -1 });`);\n\nconst harness = createHarness(sandbox);\n// pass harness.tools + harness.systemPrompt to your model\nconst result = await harness.execute(\"read_file\", { path: \"index.html\" });\n```\n\n## Install\n\n```bash\nnpm install @clipra/lumina-sandbox\n```\n\nThis repo vendors the source. Copy `packages/lumina-sandbox` into your project, or:\n\n```json\n\"dependencies\": { \"@clipra/lumina-sandbox\": \"file:./packages/lumina-sandbox\" }\n```\n\n**Next.js** — add to `next.config.ts`:\n\n```ts\nconst nextConfig = { transpilePackages: [\"@clipra/lumina-sandbox\"] };\nexport default nextConfig;\n```\n\nReact components are **client-only** (`\"use client\"`). File tools work on the server.\n\nOptional, for reliable screenshots:\n\n```bash\ncp node_modules/@clipra/lumina-sandbox/assets/html2canvas.min.js public/html2canvas.min.js\n```\n\nThe preview already falls back to jsDelivr if that file is missing.\n\n## What you get\n\n| Layer | Import | Runs |\n|---|---|---|\n| Core `Sandbox` class, files, libraries, snapshot, file tools | `@clipra/lumina-sandbox` | Server + client |\n| OpenAI-compatible tool schemas + system prompt | `@clipra/lumina-sandbox` | Server + client |\n| `createHarness()` agent loop helper | `@clipra/lumina-sandbox` | Server (files) / client (live tools) |\n| `mountPreview()` vanilla iframe | `@clipra/lumina-sandbox` | Client only |\n| `<LuminaPreview />` | `@clipra/lumina-sandbox/react` | Client only |\n| `compile()` → `srcdoc` HTML | `@clipra/lumina-sandbox` | Client (server returns a placeholder) |\n\n## Quick start (React / Next.js App Router)\n\n```tsx\n\"use client\";\n\nimport { Sandbox, createHarness } from \"@clipra/lumina-sandbox\";\nimport { LuminaPreview, useLuminaSandbox } from \"@clipra/lumina-sandbox/react\";\n\nexport function Playground() {\n  const sandbox = useLuminaSandbox({ template: \"blank\" });\n  const harness = createHarness(sandbox, { previewId: sandbox.id });\n  void harness;\n\n  return (\n    <div style={{ height: \"100dvh\" }}>\n      <LuminaPreview\n        source={sandbox}\n        onConsole={(e) => sandbox.pushConsole(e)}\n      />\n    </div>\n  );\n}\n```\n\n## Agent harness (bring your own model)\n\n```ts\nimport { createHarness, Sandbox } from \"@clipra/lumina-sandbox\";\n\nconst sandbox = Sandbox.create({ template: \"blank\" });\nconst harness = createHarness(sandbox);\n\nconst messages = [\n  { role: \"system\", content: harness.systemPrompt },\n  { role: \"user\", content: harness.snapshot() + \"\\n\\nBuild a GSAP landing page.\" },\n];\n\nconst completion = await client.chat.completions.create({\n  model: \"deepseek-v4-pro\",\n  messages,\n  tools: harness.tools,\n});\n\nfor (const call of completion.choices[0].message.tool_calls ?? []) {\n  const result = await harness.execute(call.function.name, call.function.arguments);\n  messages.push({\n    role: \"tool\",\n    tool_call_id: call.id,\n    content: result.result,\n  });\n  if (result.image) {\n    messages.push({\n      role: \"user\",\n      content: [\n        { type: \"text\", text: \"Live preview screenshot.\" },\n        { type: \"image_url\", image_url: { url: result.image } },\n      ],\n    });\n  }\n}\n```\n\nLive tools (`take_screenshot`, `inspect_layout`, `inspect_dom`, `eval_js`, `set_device`) need `<LuminaPreview />` or `mountPreview()` in the browser. File tools do not.\n\nCopy-paste: [`examples/harness-loop.ts`](./examples/harness-loop.ts), [`examples/nextjs-preview.tsx`](./examples/nextjs-preview.tsx), [`examples/nextjs-route.ts`](./examples/nextjs-route.ts).\n\n## Docs\n\n- [AGENTS.md](./AGENTS.md) — **start here** if an AI is wiring this into a product\n- [docs/INTEGRATE.md](./docs/INTEGRATE.md) — architecture, persistence, security\n- [docs/TOOLS.md](./docs/TOOLS.md) — tool schemas and rules\n- [docs/HARNESS.md](./docs/HARNESS.md) — agent loop, snapshot, screenshots\n- [docs/NEXTJS.md](./docs/NEXTJS.md) — App Router, route handlers, client preview\n\n## Templates\n\n`blank` · `north` · `kinetic` (GSAP) · `orbital` (Three.js) · `field` (canvas) · `pulse`\n\n```ts\nSandbox.templates();\nSandbox.create({ template: \"orbital\" });\n```\n\n## Libraries\n\n`gsap` `three` `anime` `motion` `lenis` `p5` `pixi` `matter` `cannon` `lilgui` `confetti` `howler` `tone` `tailwind`\n\n```ts\nsandbox.addLibrary(\"gsap\");\n// then in main.js:\nimport { gsap } from \"gsap\";\n```\n","readmeFilename":"README.md","_rev":"1-14481bbbd560a53fdba6948b775fc63f"}