@proto-labs-inc/islands 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Proto Labs Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @proto-labs-inc/islands
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shows Proto prototype alternates inside your own running dev server, without copying your app or changing its source.
+
+## Setup
+
+Next.js:
+
+```ts
+// next.config.ts
+import { withProto } from "@proto-labs-inc/islands/next";
+
+export default withProto(nextConfig);
+```
+
+Vite (React, Svelte, SvelteKit, TanStack Start and others):
+
+```ts
+// vite.config.ts
+import { protoIslands } from "@proto-labs-inc/islands/vite";
+
+export default defineConfig({ plugins: [protoIslands(), /* your plugins */] });
+```
+
+Islands run only on your dev server. A production build ignores the plugin unless `PROTO_ISLANDS=1` turns it on for a preview deploy, and `PROTO_ISLANDS=0` turns it off everywhere.
+
+## How it works
+
+Proto's agent writes alternates into `.proto/` next to your build config. While your app compiles, the plugin wraps each recorded spot in an island, in memory only. The Proto Frame picks an alternate and the island swaps it in place, with no reload. Files named `*.generated.*` are rebuilt by the plugin and ignored by git.
+
+Supports React and Svelte.

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@proto-labs-inc/islands",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Proto's islands: show prototype variants inside a maker's own running app, without changing its source.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/proto-labs-inc/proto.git",
+    "directory": "packages/islands"
+  },
+  "type": "module",
+  "exports": {
+    "./next": "./src/next.js",
+    "./vite": "./src/vite.js",
+    "./loader": "./src/loader.cjs",
+    "./react": "./src/react.js",
+    "./svelte": "./src/svelte.js",
+    "./registry": "./src/registry.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "svelte": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@babel/parser": "^7.28.0",
+    "magic-string": "^0.30.17"
+  }
+}

package/src/VariantFailed.svelte

@@ -0,0 +1,8 @@
+<script>
+	export let message = "";
+	export let variant = "";
+</script>
+
+<div role="alert" data-proto-failed={variant} style="border: 1px dashed #d92d20; border-radius: 8px; padding: 12px; color: #b42318; font: 13px/1.4 system-ui, sans-serif; background: #fef3f2">
+	Proto variant "{variant}" failed: {message}
+</div>

package/src/loader.cjs

@@ -0,0 +1,16 @@
+const { join } = require("node:path");
+
+/** Webpack and Turbopack loader: wraps recorded spots in islands, leaves every other file as it is. */
+module.exports = function protoIslandsLoader(source) {
+  const callback = this.async();
+  const { root } = this.getOptions();
+  this.addDependency(join(root, ".proto", "targets.generated.json"));
+  import("./transform.js").then(
+    ({ transformFile }) => {
+      const result = transformFile(root, this.resourcePath, source);
+      if (!result) return callback(null, source);
+      callback(null, result.code, result.map);
+    },
+    error => callback(error),
+  );
+};

package/src/next.js

@@ -0,0 +1,47 @@
+import { createRequire } from "node:module";
+import { watchRegistry } from "./registry.js";
+
+const loader = createRequire(import.meta.url).resolve("./loader.cjs");
+const SOURCE = /\.(tsx|jsx|ts|js|mjs)$/;
+
+/** One response header with any ban on being framed removed; none when nothing else is left in it. */
+export function allowFraming({ key, value }) {
+  const name = key.toLowerCase();
+  if (name === "x-frame-options") return [];
+  if (name !== "content-security-policy") return [{ key, value }];
+  const rest = value.split(";").map(part => part.trim()).filter(part => part && !/^frame-ancestors\b/i.test(part)).join("; ");
+  return rest ? [{ key, value: rest }] : [];
+}
+
+/**
+ * Next.js setup: `export default withProto(nextConfig)`. Islands run only in
+ * `next dev`, unless PROTO_ISLANDS=1 turns them on for a preview build;
+ * a normal production build never reads .proto.
+ */
+export function withProto(config = {}, { root = process.cwd() } = {}) {
+  if (process.env.PROTO_ISLANDS === "0") return config;
+  const always = process.env.PROTO_ISLANDS === "1";
+  // `next build` sets NODE_ENV before it loads the config. Leaving the config untouched keeps
+  // the dev-only loader out of what a build saves, such as the standalone server's copy of the config.
+  if (process.env.NODE_ENV === "production" && !always) return config;
+  if (!globalThis.__protoIslandsWatcher) globalThis.__protoIslandsWatcher = watchRegistry(root);
+  const use = { loader, options: { root } };
+  const condition = { all: [...(always ? [] : ["development"]), { not: "foreign" }, { path: SOURCE }] };
+  const rules = { ...config.turbopack?.rules };
+  const existing = rules["*"];
+  rules["*"] = [...(existing ? [existing].flat() : []), { condition, loaders: [use] }];
+  return {
+    ...config,
+    // Proto shows the app inside its Frame, so in development the app's own "never show me in a frame" rules are dropped.
+    async headers() {
+      const rules = config.headers ? await config.headers() : [];
+      return rules.map(rule => ({ ...rule, headers: rule.headers.flatMap(allowFraming) }));
+    },
+    turbopack: { ...config.turbopack, rules },
+    webpack(webpackConfig, context) {
+      const result = config.webpack ? config.webpack(webpackConfig, context) : webpackConfig;
+      if (context.dev || always) result.module.rules.push({ test: SOURCE, exclude: /node_modules/, enforce: "pre", use: [use] });
+      return result;
+    },
+  };
+}

package/src/react.js

@@ -0,0 +1,85 @@
+"use client";
+import * as React from "react";
+import { Component, Fragment, Suspense, createElement, useEffect, useLayoutEffect, useSyncExternalStore } from "react";
+import { selection } from "./selection.js";
+
+const modules = new WeakMap();
+
+/** Start loading a variant once; later calls share the same load. */
+function preload(load) {
+  let entry = modules.get(load);
+  if (!entry) {
+    entry = { status: "loading", module: null, error: null };
+    entry.promise = load().then(
+      module => Object.assign(entry, { status: "ready", module }),
+      error => Object.assign(entry, { status: "failed", error }),
+    );
+    modules.set(load, entry);
+  }
+  return entry;
+}
+
+/** Renders a loaded variant straight away; suspends only on the first, unloaded pick. */
+function LoadedVariant({ load, ...props }) {
+  const entry = preload(load);
+  if (entry.status === "loading") {
+    if (React.use) React.use(entry.promise);
+    else throw entry.promise;
+  }
+  if (entry.status === "failed") throw entry.error;
+  return createElement(entry.module.default, props);
+}
+
+function Rendered({ set, variant }) {
+  useLayoutEffect(() => selection.markRendered(set, variant), [set, variant]);
+  return null;
+}
+
+/** A failing variant shows a card in its own spot; the rest of the page keeps working. */
+class VariantBoundary extends Component {
+  state = { error: null };
+
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+
+  componentDidCatch(error) {
+    selection.markRendered(this.props.set, this.props.variant, "failed", String(error?.message ?? error));
+  }
+
+  render() {
+    if (!this.state.error) return this.props.children;
+    return createElement(
+      "div",
+      { role: "alert", "data-proto-failed": this.props.set, style: { border: "1px dashed #d92d20", borderRadius: 8, padding: 12, color: "#b42318", font: "13px/1.4 system-ui, sans-serif", background: "#fef3f2" } },
+      `Proto variant "${this.props.variant}" failed: ${String(this.state.error?.message ?? this.state.error)}`,
+    );
+  }
+}
+
+/**
+ * One spot in the maker's app. Renders the original children until the
+ * Frame picks a variant; a variant gets the spot's original props, the
+ * component's values it reads (`scope`) and the original element itself.
+ */
+export function ProtoIsland({ set, title, variants, scope, children }) {
+  useEffect(() => {
+    selection.register(set, { title, variants: Object.fromEntries(Object.entries(variants).map(([id, variant]) => [id, variant.title])) });
+    // Load every variant while the page is idle, so even the first swap is instant.
+    const idle = window.requestIdleCallback ?? (callback => setTimeout(callback, 200));
+    idle(() => Object.values(variants).forEach(variant => preload(variant.load)));
+  }, [set, title, variants]);
+  const chosen = useSyncExternalStore(selection.subscribe, () => selection.get(set), () => null);
+  const variant = chosen ? variants[chosen] : null;
+  if (!variant) return createElement(Fragment, null, children, createElement(Rendered, { set, variant: "original" }));
+  return createElement(
+    VariantBoundary,
+    { key: chosen, set, variant: chosen },
+    createElement(
+      Suspense,
+      { fallback: children },
+      createElement(LoadedVariant, { load: variant.load, props: children?.props ?? {}, scope: scope ?? {}, original: children }),
+      createElement(Rendered, { set, variant: chosen }),
+    ),
+  );
+}

package/src/registry.js

@@ -0,0 +1,147 @@
+import { existsSync, readdirSync, readFileSync, statSync, watch, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, extname, join, relative, sep } from "node:path";
+
+/**
+ * The .proto folder next to an app's own config: one folder per prototype,
+ * one folder per variant set (a spot in the app), one folder per variant.
+ *
+ *   .proto/prototypes/<prototype>/<set>/set.json
+ *   .proto/prototypes/<prototype>/<set>/<variant>/variant.json + Variant.tsx | Variant.svelte
+ *
+ * Everything named *.generated.* is rebuilt from those files and never committed.
+ */
+export const PROTO_DIR = ".proto";
+export const TARGETS_FILE = "targets.generated.json";
+const ISLAND_FILE = "island.generated.js";
+const SVELTE = new Set([".svelte"]);
+const REACT = new Set([".tsx", ".jsx", ".ts", ".js", ".mjs"]);
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function folders(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true }).filter(entry => entry.isDirectory() && !entry.name.startsWith(".")).map(entry => entry.name).sort();
+}
+
+/** Every set with its variants, read from disk. */
+export function readSets(root) {
+  const prototypes = join(root, PROTO_DIR, "prototypes");
+  const sets = [];
+  for (const prototype of folders(prototypes)) {
+    for (const setName of folders(join(prototypes, prototype))) {
+      const dir = join(prototypes, prototype, setName);
+      const set = readJson(join(dir, "set.json"));
+      if (!set?.target?.file || !set.target.element) continue;
+      const variants = [];
+      for (const variantName of folders(dir)) {
+        const variantDir = join(dir, variantName);
+        const meta = readJson(join(variantDir, "variant.json"));
+        if (!meta) continue;
+        const entry = meta.entry ?? readdirSync(variantDir).find(file => /^Variant\.(tsx|jsx|js|svelte)$/.test(file));
+        if (!entry || !existsSync(join(variantDir, entry))) continue;
+        variants.push({ id: variantName, title: meta.title ?? variantName, entry: `./${variantName}/${entry}` });
+      }
+      sets.push({ key: `${prototype}.${setName}`, title: set.title ?? setName, dir, target: set.target, variants });
+    }
+  }
+  return sets;
+}
+
+function islandModule(set) {
+  const framework = SVELTE.has(extname(set.target.file)) ? "svelte" : "react";
+  const variants = set.variants
+    .map(variant => `  ${JSON.stringify(variant.id)}: { title: ${JSON.stringify(variant.title)}, load: () => import(${JSON.stringify(variant.entry)}) },`)
+    .join("\n");
+  if (framework === "svelte") {
+    return `import { island } from "@proto-labs-inc/islands/svelte";\n\nexport default island(${JSON.stringify(set.key)}, ${JSON.stringify(set.title)}, {\n${variants}\n});\n`;
+  }
+  return `"use client";
+import { createElement } from "react";
+import { ProtoIsland } from "@proto-labs-inc/islands/react";
+
+const variants = {
+${variants}
+};
+
+export default function ProtoSet(props) {
+  return createElement(ProtoIsland, { ...props, set: ${JSON.stringify(set.key)}, title: ${JSON.stringify(set.title)}, variants });
+}
+`;
+}
+
+function writeIfChanged(file, content) {
+  if (existsSync(file) && readFileSync(file, "utf8") === content) return false;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, content);
+  return true;
+}
+
+/**
+ * Rebuild each set's island module and the list of target files. Returns
+ * the target files whose islands were added or removed, so a dev server can
+ * recompile exactly those.
+ */
+export function generate(root) {
+  const protoDir = join(root, PROTO_DIR);
+  if (!existsSync(protoDir)) return [];
+  writeIfChanged(join(protoDir, ".gitignore"), "*.generated.*\n");
+  const targets = {};
+  for (const set of readSets(root)) {
+    const module = join(set.dir, ISLAND_FILE);
+    writeIfChanged(module, islandModule(set));
+    const file = set.target.file.split("/").join(sep);
+    (targets[file] ??= []).push({ key: set.key, module, element: set.target.element, in: set.target.in ?? null, nth: set.target.nth ?? 0 });
+  }
+  const targetsFile = join(protoDir, TARGETS_FILE);
+  const before = readJson(targetsFile) ?? {};
+  const content = `${JSON.stringify(targets, null, 2)}\n`;
+  if (!writeIfChanged(targetsFile, content)) return [];
+  const changed = new Set([...Object.keys(before), ...Object.keys(targets)].filter(file => JSON.stringify(before[file]) !== JSON.stringify(targets[file])));
+  return [...changed].map(file => join(root, file));
+}
+
+let cached = { file: null, mtime: 0, targets: {} };
+
+/** The islands recorded for one source file, or none. */
+export function targetsFor(root, file) {
+  const targetsFile = join(root, PROTO_DIR, TARGETS_FILE);
+  let mtime = 0;
+  try {
+    mtime = statSync(targetsFile).mtimeMs;
+  } catch {
+    return [];
+  }
+  if (cached.file !== targetsFile || cached.mtime !== mtime) cached = { file: targetsFile, mtime, targets: readJson(targetsFile) ?? {} };
+  return cached.targets[relative(root, file)] ?? [];
+}
+
+/** Keep the generated files current while a dev server runs. */
+export function watchRegistry(root, onTargetsChanged = () => {}) {
+  const protoDir = join(root, PROTO_DIR);
+  mkdirSync(join(protoDir, "prototypes"), { recursive: true });
+  generate(root);
+  let timer = null;
+  const watcher = watch(protoDir, { recursive: true }, (_event, name) => {
+    if (name && name.includes(".generated.")) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      const changed = generate(root);
+      if (changed.length) onTargetsChanged(changed);
+    }, 30);
+  });
+  watcher.unref?.();
+  return watcher;
+}
+
+export function frameworkOf(file) {
+  const extension = extname(file);
+  if (SVELTE.has(extension)) return "svelte";
+  if (REACT.has(extension)) return "react";
+  return null;
+}

package/src/selection.js

@@ -0,0 +1,96 @@
+/**
+ * Which variant each island shows, shared by every island on the page.
+ * It starts from the address (?v.<prototype>.<set>=<variant>) and follows
+ * the Frame's messages, so a swap re-renders one island and nothing else.
+ * One copy lives on window, so islands from different bundles agree.
+ */
+const GLOBAL = "__protoIslands";
+const PARAM = "v.";
+
+function post(message) {
+  if (window.parent !== window) window.parent.postMessage(message, "*");
+}
+
+/** The page-space outline of the nodes a swap put on screen, or null when it drew no DOM (a WebGL scene). */
+function regionOf(nodes) {
+  const added = new Set(nodes);
+  let box = null;
+  for (const node of added) {
+    if (!node.isConnected || added.has(node.parentNode)) continue;
+    if (node.nodeType === Node.TEXT_NODE && !node.textContent.trim()) continue;
+    const range = document.createRange();
+    range.selectNode(node);
+    const rect = range.getBoundingClientRect();
+    if (!rect.width && !rect.height) continue;
+    box = box
+      ? { left: Math.min(box.left, rect.left), top: Math.min(box.top, rect.top), right: Math.max(box.right, rect.right), bottom: Math.max(box.bottom, rect.bottom) }
+      : { left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom };
+  }
+  if (!box) return null;
+  return { x: Math.round(box.left + scrollX), y: Math.round(box.top + scrollY), width: Math.round(box.right - box.left), height: Math.round(box.bottom - box.top) };
+}
+
+function createSelection() {
+  const chosen = new Map();
+  const listeners = new Set();
+  const sets = new Map();
+  const rendered = new Map();
+  // Watches the DOM from a pick until its island has rendered, to learn where the island sits.
+  let watching = null;
+  for (const [key, value] of new URLSearchParams(window.location.search)) {
+    if (key.startsWith(PARAM) && value && value !== "original") chosen.set(key.slice(PARAM.length), value);
+  }
+  const announce = () => post({ type: "proto:islands", sets: Object.fromEntries(sets) });
+  const selection = {
+    get: set => chosen.get(set) ?? null,
+    select(set, variant) {
+      if (!variant || variant === "original") chosen.delete(set);
+      else chosen.set(set, variant);
+      watching?.observer.disconnect();
+      const added = [];
+      const observer = new MutationObserver(records => records.forEach(record => added.push(...record.addedNodes)));
+      observer.observe(document.body, { childList: true, subtree: true, characterData: true });
+      watching = { set, variant: variant && variant !== "original" ? variant : "original", added, observer };
+      listeners.forEach(listener => listener());
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    register(set, info) {
+      sets.set(set, info);
+      announce();
+    },
+    sets: () => Object.fromEntries(sets),
+    markRendered(set, variant, status = "ready", message = null) {
+      let rect = rendered.get(set)?.rect ?? null;
+      if (watching?.set === set && watching.variant === variant) {
+        watching.observer.takeRecords().forEach(record => watching.added.push(...record.addedNodes));
+        watching.observer.disconnect();
+        rect = regionOf(watching.added);
+        watching = null;
+      }
+      rendered.set(set, { variant, status, message, rect, at: performance.now() });
+      post({ type: "proto:rendered", set, variant, status, message, rect });
+    },
+    rendered: set => rendered.get(set) ?? null,
+  };
+  window.addEventListener("message", event => {
+    const data = event.data;
+    if (data?.type === "proto:select") selection.select(data.set, data.variant);
+    else if (data?.type === "proto:islands?") announce();
+  });
+  return selection;
+}
+
+const serverSelection = {
+  get: () => null,
+  select() {},
+  subscribe: () => () => {},
+  register() {},
+  sets: () => ({}),
+  markRendered() {},
+  rendered: () => null,
+};
+
+export const selection = typeof window === "undefined" ? serverSelection : (window[GLOBAL] ??= createSelection());

package/src/svelte.js

@@ -0,0 +1,66 @@
+import { tick } from "svelte";
+import { readable } from "svelte/store";
+import { selection } from "./selection.js";
+import VariantFailed from "./VariantFailed.svelte";
+
+/**
+ * Svelte has no error boundary, so a variant that throws while starting would
+ * break the page. The guard builds the variant, and an error card in its
+ * place when it throws. `new.target` covers Svelte 4 classes and Svelte 5 functions.
+ */
+function guard(Variant, variant, onError) {
+  return function GuardedVariant(...args) {
+    try {
+      return new.target ? new Variant(...args) : Variant(...args);
+    } catch (error) {
+      const message = String(error?.message ?? error);
+      onError(message);
+      if (new.target) return new VariantFailed({ ...args[0], props: { message, variant } });
+      return VariantFailed(args[0], { message, variant });
+    }
+  };
+}
+
+/**
+ * One spot in a Svelte app. The store holds the variant component to render,
+ * or null for the original. Variant modules load on first pick.
+ */
+export function island(set, title, variants) {
+  return () => {
+    selection.register(set, { title, variants: Object.fromEntries(Object.entries(variants).map(([id, variant]) => [id, variant.title])) });
+    // Load every variant while the page is idle, so even the first swap is instant.
+    if (typeof window !== "undefined") {
+      const idle = window.requestIdleCallback ?? (callback => setTimeout(callback, 200));
+      idle(() => Object.values(variants).forEach(variant => variant.load().catch(() => {})));
+    }
+    return readable(null, update => {
+      let current = Symbol("none");
+      const follow = async () => {
+        const chosen = selection.get(set);
+        if (chosen === current) return;
+        current = chosen;
+        const variant = chosen ? variants[chosen] : null;
+        if (!variant) {
+          update(null);
+          await tick();
+          selection.markRendered(set, "original");
+          return;
+        }
+        try {
+          const module = await variant.load();
+          if (current !== chosen) return;
+          let failure = null;
+          update(guard(module.default, chosen, message => (failure = message)));
+          await tick();
+          if (failure) selection.markRendered(set, chosen, "failed", failure);
+          else selection.markRendered(set, chosen);
+        } catch (error) {
+          update(null);
+          selection.markRendered(set, chosen, "failed", String(error?.message ?? error));
+        }
+      };
+      follow();
+      return selection.subscribe(follow);
+    });
+  };
+}

package/src/transform.js

@@ -0,0 +1,221 @@
+import { createRequire } from "node:module";
+import { dirname, join, relative, sep } from "node:path";
+import { parse as parseJs } from "@babel/parser";
+import MagicString from "magic-string";
+import { frameworkOf, targetsFor } from "./registry.js";
+
+const SKIP_KEYS = new Set(["loc", "start", "end", "extra", "leadingComments", "trailingComments", "innerComments", "typeAnnotation", "typeParameters", "typeArguments", "returnType", "range"]);
+
+function walk(node, visit, parent = null, key = null) {
+  if (!node || typeof node.type !== "string") return;
+  if (visit(node, parent, key) === false) return;
+  for (const childKey of Object.keys(node)) {
+    if (SKIP_KEYS.has(childKey)) continue;
+    const value = node[childKey];
+    if (Array.isArray(value)) value.forEach(child => walk(child, visit, node, childKey));
+    else if (value && typeof value.type === "string") walk(value, visit, node, childKey);
+  }
+}
+
+function importPath(fromFile, toFile) {
+  const path = relative(dirname(fromFile), toFile).split(sep).join("/");
+  return path.startsWith(".") ? path : `./${path}`;
+}
+
+/** Wrap each recorded spot in a source file with its island. Returns null when the file has none. */
+export function transformFile(root, file, source) {
+  const targets = targetsFor(root, file);
+  if (!targets.length) return null;
+  const framework = frameworkOf(file);
+  if (framework === "react") return transformReact(file, source, targets);
+  if (framework === "svelte") return transformSvelte(root, file, source, targets);
+  return null;
+}
+
+function jsxName(name) {
+  if (name.type === "JSXIdentifier") return name.name;
+  if (name.type === "JSXMemberExpression") return `${jsxName(name.object)}.${name.property.name}`;
+  if (name.type === "JSXNamespacedName") return `${name.namespace.name}:${name.name.name}`;
+  return "";
+}
+
+function patternNames(pattern, names) {
+  if (!pattern) return;
+  switch (pattern.type) {
+    case "Identifier":
+      names.add(pattern.name);
+      break;
+    case "ObjectPattern":
+      for (const property of pattern.properties) patternNames(property.type === "RestElement" ? property.argument : property.value, names);
+      break;
+    case "ArrayPattern":
+      pattern.elements.forEach(element => patternNames(element, names));
+      break;
+    case "AssignmentPattern":
+      patternNames(pattern.left, names);
+      break;
+    case "RestElement":
+      patternNames(pattern.argument, names);
+      break;
+    case "TSParameterProperty":
+      patternNames(pattern.parameter, names);
+      break;
+  }
+}
+
+function isFunction(node) {
+  return node?.type === "FunctionDeclaration" || node?.type === "FunctionExpression" || node?.type === "ArrowFunctionExpression";
+}
+
+/** The function declared under this name, looking through wrappers like memo() and forwardRef(). */
+function findComponent(program, name) {
+  let found = null;
+  walk(program, node => {
+    if (found) return false;
+    if (node.type === "FunctionDeclaration" && node.id?.name === name) found = node;
+    else if (node.type === "VariableDeclarator" && node.id?.name === name) {
+      let init = node.init;
+      while (init?.type === "CallExpression") init = init.arguments.find(argument => isFunction(argument) || argument.type === "CallExpression");
+      if (isFunction(init)) found = init;
+    }
+  });
+  return found;
+}
+
+/**
+ * The component's own values a variant may use (`scope`): its props and every
+ * top-level declaration before the spot. Later or nested names are left out,
+ * since reading them at the spot would fail.
+ */
+function scopeOf(component, element) {
+  if (!component) return [];
+  const names = new Set();
+  component.params?.forEach(param => patternNames(param, names));
+  if (component.body?.type !== "BlockStatement") return [...names];
+  for (const statement of component.body.body) {
+    if (statement.start >= element.start) break;
+    if (statement.type === "VariableDeclaration") statement.declarations.forEach(item => patternNames(item.id, names));
+    else if (statement.type === "FunctionDeclaration" && statement.id) names.add(statement.id.name);
+  }
+  return [...names];
+}
+
+function transformReact(file, source, targets) {
+  let ast;
+  try {
+    ast = parseJs(source, { sourceType: "module", plugins: ["jsx", "typescript"], errorRecovery: false });
+  } catch {
+    return null;
+  }
+  const code = new MagicString(source);
+  const imports = [];
+  const wraps = new Map();
+  targets.forEach((target, index) => {
+    const container = target.in ? findComponent(ast.program, target.in) : ast.program;
+    if (!container) return;
+    const matches = [];
+    walk(container, node => {
+      if (node.type === "JSXElement" && jsxName(node.openingElement.name) === target.element) matches.push(node);
+    });
+    const element = matches[target.nth];
+    if (!element) return;
+    const name = `__ProtoSet${index}`;
+    imports.push(`import ${name} from ${JSON.stringify(importPath(file, target.module))};`);
+    const scope = scopeOf(target.in ? container : null, element);
+    const list = wraps.get(element) ?? [];
+    list.push({ name, scope });
+    wraps.set(element, list);
+  });
+  if (!imports.length) return null;
+  for (const [element, list] of wraps) {
+    const open = list.map(({ name, scope }) => `<${name} scope={{ ${scope.join(", ")} }}>`).join("");
+    const close = list.map(({ name }) => `</${name}>`).reverse().join("");
+    code.prependRight(element.start, open);
+    code.appendLeft(element.end, close);
+  }
+  const directives = ast.program.directives;
+  const at = directives.length ? directives.at(-1).end : 0;
+  if (at) code.appendLeft(at, `\n${imports.join("\n")}`);
+  else code.prepend(`${imports.join("\n")}\n`);
+  return { code: code.toString(), map: code.generateMap({ source: file, includeContent: true, hires: true }) };
+}
+
+/** Blank out <script> and <style> bodies so the markup parses without a TypeScript preprocessor. Positions stay the same. */
+function blankBlocks(source) {
+  return source.replace(/(<(script|style)\b[^>]*>)([\s\S]*?)(<\/\2>)/g, (_match, open, _tag, body, close) => open + body.replace(/[^\n]/g, " ") + close);
+}
+
+function svelteNodes(ast) {
+  return ast.html ?? ast.fragment ?? ast;
+}
+
+function instanceScript(source) {
+  for (const match of source.matchAll(/<script(\s[^>]*)?>/g)) {
+    const attributes = match[1] ?? "";
+    if (/context\s*=\s*["']module["']|\bmodule\b/.test(attributes)) continue;
+    const bodyStart = match.index + match[0].length;
+    const bodyEnd = source.indexOf("</script>", bodyStart);
+    return { bodyStart, body: source.slice(bodyStart, bodyEnd) };
+  }
+  return null;
+}
+
+/** Top-level names in the component's script, including `$:` reactive ones. */
+function scriptNames(body) {
+  const names = new Set();
+  let ast;
+  try {
+    ast = parseJs(body, { sourceType: "module", plugins: ["typescript"] });
+  } catch {
+    return names;
+  }
+  for (const statement of ast.program.body) {
+    const declaration = statement.type.startsWith("Export") && statement.declaration ? statement.declaration : statement;
+    if (declaration.type === "VariableDeclaration") declaration.declarations.forEach(item => patternNames(item.id, names));
+    else if (declaration.type === "FunctionDeclaration" && declaration.id) names.add(declaration.id.name);
+    else if (declaration.type === "LabeledStatement" && declaration.label.name === "$" && declaration.body.type === "ExpressionStatement") {
+      const expression = declaration.body.expression;
+      if (expression.type === "AssignmentExpression") patternNames(expression.left, names);
+    }
+  }
+  return names;
+}
+
+function transformSvelte(root, file, source, targets) {
+  const require = createRequire(join(root, "package.json"));
+  let ast;
+  try {
+    ast = require("svelte/compiler").parse(blankBlocks(source));
+  } catch {
+    return null;
+  }
+  const script = instanceScript(source);
+  const declared = script ? scriptNames(script.body) : new Set();
+  const code = new MagicString(source);
+  const setup = [];
+  targets.forEach((target, index) => {
+    const matches = [];
+    walk(svelteNodes(ast), node => {
+      if ((node.type === "InlineComponent" || node.type === "Element" || node.type === "Component" || node.type === "RegularElement") && node.name === target.element) matches.push(node);
+    });
+    const node = matches[target.nth];
+    if (!node) return;
+    const pick = `__protoPick${index}`;
+    setup.push(`import __protoSet${index} from ${JSON.stringify(importPath(file, target.module))};`, `const ${pick} = __protoSet${index}();`);
+    if (/^[A-Z]/.test(node.name)) {
+      code.overwrite(node.start, node.start + 1 + node.name.length, `<svelte:component this={$${pick} ?? ${node.name}}`);
+      if (source.slice(node.end - 2, node.end) !== "/>") {
+        const closeAt = source.lastIndexOf("</", node.end);
+        code.overwrite(closeAt, node.end, "</svelte:component>");
+      }
+    } else {
+      const scope = [...declared];
+      code.prependRight(node.start, `{#if $${pick}}<svelte:component this={$${pick}} scope={{ ${scope.join(", ")} }} />{:else}`);
+      code.appendLeft(node.end, "{/if}");
+    }
+  });
+  if (!setup.length) return null;
+  if (script) code.appendLeft(script.bodyStart, `\n${setup.join("\n")}\n`);
+  else code.prepend(`<script>\n${setup.join("\n")}\n</script>\n`);
+  return { code: code.toString(), map: code.generateMap({ source: file, includeContent: true, hires: true }) };
+}

package/src/vite.js

@@ -0,0 +1,47 @@
+import { resolve } from "node:path";
+import { transformFile } from "./transform.js";
+import { PROTO_DIR, watchRegistry } from "./registry.js";
+
+/**
+ * Vite setup: add `protoIslands()` to `plugins`. Covers React, Svelte and
+ * anything else on Vite. Islands run only in `vite dev`, unless
+ * PROTO_ISLANDS=1 turns them on for a preview build.
+ */
+export function protoIslands({ root } = {}) {
+  let appRoot = root;
+  return {
+    name: "proto-islands",
+    enforce: "pre",
+    apply: (_config, env) => process.env.PROTO_ISLANDS !== "0" && (env.command === "serve" || process.env.PROTO_ISLANDS === "1"),
+    configResolved(config) {
+      appRoot ??= config.root;
+      // Frameworks like SvelteKit set their own list of servable folders; .proto joins whatever list won.
+      config.server.fs.allow.push(resolve(appRoot, PROTO_DIR));
+    },
+    configureServer(server) {
+      // Proto shows the app inside its Frame, so the dev server's own "never show me in a frame" headers are dropped.
+      server.middlewares.use((_request, response, next) => {
+        const setHeader = response.setHeader.bind(response);
+        response.setHeader = (name, value) => {
+          const lower = String(name).toLowerCase();
+          if (lower === "x-frame-options") return response;
+          if (lower === "content-security-policy") {
+            const rest = String(value).split(";").map(part => part.trim()).filter(part => part && !/^frame-ancestors\b/i.test(part)).join("; ");
+            return rest ? setHeader(name, rest) : response;
+          }
+          return setHeader(name, value);
+        };
+        next();
+      });
+      watchRegistry(appRoot, files => {
+        for (const file of files) {
+          for (const module of server.moduleGraph.getModulesByFile(file) ?? []) server.reloadModule(module);
+        }
+      });
+    },
+    transform(source, id) {
+      const result = transformFile(appRoot, id.split("?")[0], source);
+      return result ? { code: result.code, map: result.map } : null;
+    },
+  };
+}