preact-alchemy 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Alec Larson
+
+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/dist/chunk-JSNOUUYJ.js

@@ -0,0 +1,551 @@
+// src/transform.ts
+import { parse } from "meriyah";
+import { walk } from "zimmerframe";
+import MagicString from "magic-string";
+var Scope = class {
+  parent;
+  bindings = /* @__PURE__ */ new Map();
+  constructor(parent) {
+    this.parent = parent;
+  }
+  add(name, reactive) {
+    this.bindings.set(name, { reactive });
+  }
+  resolve(name) {
+    for (let scope = this; scope; scope = scope.parent) {
+      const binding = scope.bindings.get(name);
+      if (binding) return binding;
+    }
+    return null;
+  }
+};
+var SIGNAL_BASE = "__alchemy_signal";
+var visitors = {
+  BlockStatement(node, context) {
+    const { state, next } = context;
+    const blockScope = new Scope(state.scope);
+    collectBlockBindings(
+      node.body,
+      blockScope,
+      state.functionScope,
+      isReactiveScope(state)
+    );
+    next({ ...state, scope: blockScope });
+  },
+  SwitchStatement(node, context) {
+    const { state, next } = context;
+    const switchScope = new Scope(state.scope);
+    collectSwitchBindings(
+      node.cases,
+      switchScope,
+      state.functionScope,
+      isReactiveScope(state)
+    );
+    next({ ...state, scope: switchScope });
+  },
+  ForStatement: enterLoop,
+  ForInStatement: enterLoop,
+  ForOfStatement: enterLoop,
+  WhileStatement: enterLoop,
+  DoWhileStatement: enterLoop,
+  FunctionDeclaration: enterFunction,
+  FunctionExpression: enterFunction,
+  ArrowFunctionExpression: enterFunction,
+  CatchClause(node, context) {
+    const { state, next } = context;
+    const catchScope = new Scope(state.scope);
+    if (node.param) {
+      const { names } = collectPatternIdentifiers(node.param);
+      for (const name of names) {
+        catchScope.add(name, false);
+      }
+    }
+    next({ ...state, scope: catchScope });
+  },
+  VariableDeclaration: handleVariableDeclaration,
+  Property: handleProperty,
+  Identifier: handleIdentifier
+};
+function transform(code, id) {
+  const cleanId = id ? id.split("?")[0] : void 0;
+  const isTypeScriptFile = !!cleanId && /\.[cm]?tsx?$/.test(cleanId);
+  let ast;
+  try {
+    ast = parse(code, {
+      sourceType: "module",
+      jsx: true,
+      ranges: true
+    });
+  } catch (error) {
+    if (isTypeScriptFile) {
+      warn(cleanId, "TypeScript syntax is not supported; skipping file");
+    } else {
+      warn(
+        cleanId,
+        `Failed to parse${cleanId ? ` ${cleanId}` : ""}; skipping file`
+      );
+    }
+    return { code };
+  }
+  const alchemicalFunctions = findAlchemicalFunctions(ast);
+  if (alchemicalFunctions.length === 0) return { code };
+  const s = new MagicString(code);
+  const usedNames = collectAllBindingNames(ast);
+  const signalAlias = uniqueAlias(SIGNAL_BASE, usedNames);
+  const alchemicalSet = new Set(alchemicalFunctions);
+  let usedSignal = false;
+  const markSignalUsed = () => {
+    usedSignal = true;
+  };
+  for (const fn of alchemicalFunctions) {
+    const directive = getDirectiveStatement(fn);
+    if (directive && hasRange(directive)) {
+      s.remove(directive.start, directive.end);
+    }
+    transformAlchemicalFunction(fn, {
+      scope: new Scope(),
+      functionScope: new Scope(),
+      functionDepth: 0,
+      loopDepth: 0,
+      signalAlias,
+      s,
+      code,
+      alchemicalSet,
+      markSignalUsed,
+      warn: (message) => warn(cleanId, message)
+    });
+  }
+  if (usedSignal) {
+    injectSignalImport(s, code, signalAlias);
+  }
+  if (!s.hasChanged()) return { code };
+  return {
+    code: s.toString(),
+    map: s.generateMap({ hires: true, source: cleanId })
+  };
+}
+function enterLoop(node, context) {
+  const { state, next } = context;
+  const loopScope = new Scope(state.scope);
+  const loopState = {
+    ...state,
+    scope: loopScope,
+    loopDepth: state.loopDepth + 1
+  };
+  if (node.type === "ForStatement" || node.type === "ForInStatement" || node.type === "ForOfStatement") {
+    collectLoopBindings(
+      node,
+      loopScope,
+      state.functionScope,
+      isReactiveScope(loopState)
+    );
+  }
+  next(loopState);
+}
+function enterFunction(node, context) {
+  const { state, next } = context;
+  if (state.alchemicalSet.has(node)) return;
+  const functionScope = new Scope(state.scope);
+  addFunctionBindings(node, functionScope);
+  next({
+    ...state,
+    scope: functionScope,
+    functionScope,
+    functionDepth: state.functionDepth + 1,
+    loopDepth: 0
+  });
+}
+function handleVariableDeclaration(node, context) {
+  const { state, next, path } = context;
+  if (node.kind !== "let" || !isReactiveScope(state)) {
+    next();
+    return;
+  }
+  const assignments = [];
+  let hasAssignmentInsert = false;
+  for (const declarator of node.declarations) {
+    const id = declarator.id;
+    const init = declarator.init;
+    if (id.type === "Identifier") {
+      if (init && hasRange(init)) {
+        state.s.appendLeft(init.start, `${state.signalAlias}(`);
+        state.s.appendRight(init.end, `)`);
+      } else if (hasRange(id)) {
+        state.s.appendRight(id.end, ` = ${state.signalAlias}(undefined)`);
+      }
+      state.markSignalUsed();
+    } else {
+      const { names, supported } = collectPatternIdentifiers(id);
+      if (!supported) {
+        state.warn(`Unsupported destructuring pattern; skipping transform`);
+        continue;
+      }
+      for (const name of names) {
+        assignments.push(`${name} = ${state.signalAlias}(${name});`);
+      }
+      if (names.length > 0) {
+        state.markSignalUsed();
+        hasAssignmentInsert = true;
+      }
+    }
+  }
+  const parent = path[path.length - 1];
+  if (hasAssignmentInsert && !isForParent(parent) && hasRange(node)) {
+    const indent = getIndent(state.code, node.start);
+    state.s.appendRight(
+      node.end,
+      `
+${indent}${assignments.join(`
+${indent}`)}`
+    );
+  }
+  next();
+}
+function handleProperty(node, context) {
+  const { state, next, path } = context;
+  const parent = path[path.length - 1];
+  if (!parent || parent.type !== "ObjectExpression") {
+    next();
+    return;
+  }
+  if (node.kind !== "init" || !node.shorthand) {
+    next();
+    return;
+  }
+  const key = node.key;
+  const value = node.value;
+  if (key.type !== "Identifier" || value.type !== "Identifier") return;
+  const binding = state.scope.resolve(value.name);
+  if (!binding || !binding.reactive) return;
+  if (!hasRange(node)) return;
+  if (isReactiveScope(state)) {
+    state.s.overwrite(
+      node.start,
+      node.end,
+      `get ${value.name}() { return ${value.name}.value; }`
+    );
+  } else {
+    state.s.overwrite(
+      node.start,
+      node.end,
+      `${value.name}: ${value.name}.value`
+    );
+  }
+}
+function handleIdentifier(node, context) {
+  const { state, path } = context;
+  const parent = path[path.length - 1];
+  if (!parent) return;
+  if (!isReferenceIdentifier(node, parent, path)) return;
+  const binding = state.scope.resolve(node.name);
+  if (!binding || !binding.reactive) return;
+  if (parent.type === "MemberExpression" && parent.object === node) {
+    if (!parent.computed && parent.property.type === "Identifier" && parent.property.name === "value") {
+      return;
+    }
+  }
+  if (!hasRange(node)) return;
+  state.s.appendLeft(node.end, ".value");
+}
+function findAlchemicalFunctions(ast) {
+  const functions = [];
+  const maybeAdd = (node) => {
+    if (!node.body || node.body.type !== "BlockStatement") return;
+    const directive = getDirectiveStatement(node);
+    if (directive) functions.push(node);
+  };
+  walk(ast, null, {
+    FunctionDeclaration(node) {
+      maybeAdd(node);
+    },
+    FunctionExpression(node) {
+      maybeAdd(node);
+    },
+    ArrowFunctionExpression(node) {
+      maybeAdd(node);
+    }
+  });
+  return functions;
+}
+function getDirectiveStatement(fn) {
+  if (!fn.body || fn.body.type !== "BlockStatement") return null;
+  const first = fn.body.body[0];
+  if (!first || first.type !== "ExpressionStatement") return null;
+  const expression = first.expression;
+  if (!expression || expression.type !== "Literal") return null;
+  if (expression.value !== "use alchemy") return null;
+  return first;
+}
+function transformAlchemicalFunction(fn, state) {
+  if (!fn.body || fn.body.type !== "BlockStatement") return;
+  const functionScope = new Scope(state.scope);
+  const bodyScope = new Scope(functionScope);
+  addFunctionBindings(fn, functionScope);
+  const rootState = {
+    ...state,
+    scope: bodyScope,
+    functionScope,
+    functionDepth: 0,
+    loopDepth: 0
+  };
+  collectBlockBindings(
+    fn.body.body,
+    bodyScope,
+    functionScope,
+    isReactiveScope(rootState)
+  );
+  for (const statement of fn.body.body) {
+    walk(statement, rootState, visitors);
+  }
+}
+function isForParent(node) {
+  if (!node) return false;
+  return node.type === "ForStatement" || node.type === "ForInStatement" || node.type === "ForOfStatement";
+}
+function isReferenceIdentifier(node, parent, path) {
+  const grandparent = path[path.length - 2];
+  if (parent.type === "VariableDeclarator" && parent.id === node) return false;
+  if ((parent.type === "FunctionDeclaration" || parent.type === "FunctionExpression") && parent.id === node) {
+    return false;
+  }
+  if (parent.type === "ClassDeclaration" && parent.id === node) return false;
+  if (parent.type === "ClassExpression" && parent.id === node) return false;
+  if (parent.type === "ImportSpecifier" || parent.type === "ImportDefaultSpecifier" || parent.type === "ImportNamespaceSpecifier") {
+    return false;
+  }
+  if (parent.type === "ExportSpecifier") return false;
+  if (parent.type === "Property" && parent.shorthand && parent.value === node)
+    return false;
+  if (parent.type === "Property" && parent.key === node && !parent.computed)
+    return false;
+  if (parent.type === "PropertyDefinition" && parent.key === node && !parent.computed)
+    return false;
+  if (parent.type === "MemberExpression" && parent.property === node && !parent.computed)
+    return false;
+  if (parent.type === "MethodDefinition" && parent.key === node && !parent.computed)
+    return false;
+  if (parent.type === "LabeledStatement" && parent.label === node) return false;
+  if ((parent.type === "BreakStatement" || parent.type === "ContinueStatement") && parent.label === node) {
+    return false;
+  }
+  if (parent.type === "CatchClause" && parent.param === node) return false;
+  if (parent.type === "AssignmentPattern" && parent.left === node) return false;
+  if (parent.type === "RestElement" && parent.argument === node) return false;
+  if (parent.type === "ArrayPattern" || parent.type === "ObjectPattern")
+    return false;
+  if (parent.type === "Property" && grandparent?.type === "ObjectPattern") {
+    if (parent.value === node) return false;
+    if (parent.key === node && !parent.computed) return false;
+  }
+  if (parent.type === "FunctionExpression" || parent.type === "ArrowFunctionExpression" || parent.type === "FunctionDeclaration") {
+    const params = parent.params ?? [];
+    if (params.includes(node)) return false;
+  }
+  return true;
+}
+function collectAllBindingNames(ast) {
+  const names = /* @__PURE__ */ new Set();
+  const addPattern = (pattern) => {
+    const { names: collected } = collectPatternIdentifiers(pattern);
+    for (const name of collected) names.add(name);
+  };
+  walk(ast, null, {
+    VariableDeclarator(node) {
+      addPattern(node.id);
+    },
+    FunctionDeclaration(node) {
+      if (node.id) names.add(node.id.name);
+      for (const param of node.params ?? []) addPattern(param);
+    },
+    FunctionExpression(node) {
+      if (node.id) names.add(node.id.name);
+      for (const param of node.params ?? []) addPattern(param);
+    },
+    ArrowFunctionExpression(node) {
+      for (const param of node.params ?? []) addPattern(param);
+    },
+    ClassDeclaration(node) {
+      if (node.id) names.add(node.id.name);
+    },
+    ImportSpecifier(node) {
+      if (node.local) names.add(node.local.name);
+    },
+    ImportDefaultSpecifier(node) {
+      if (node.local) names.add(node.local.name);
+    },
+    ImportNamespaceSpecifier(node) {
+      if (node.local) names.add(node.local.name);
+    },
+    CatchClause(node) {
+      if (node.param) addPattern(node.param);
+    }
+  });
+  return names;
+}
+function collectBlockBindings(statements, scope, functionScope, reactiveAllowed) {
+  for (const statement of statements) {
+    collectBindingsInStatement(statement, scope, functionScope, reactiveAllowed);
+  }
+}
+function collectSwitchBindings(cases, scope, functionScope, reactiveAllowed) {
+  for (const switchCase of cases) {
+    for (const statement of switchCase.consequent) {
+      collectBindingsInStatement(
+        statement,
+        scope,
+        functionScope,
+        reactiveAllowed
+      );
+    }
+  }
+}
+function collectLoopBindings(node, scope, functionScope, reactiveAllowed) {
+  const declaration = node.type === "ForStatement" ? node.init : node.left;
+  if (declaration && declaration.type === "VariableDeclaration") {
+    collectBindingsFromDeclaration(
+      declaration,
+      scope,
+      functionScope,
+      reactiveAllowed
+    );
+  }
+}
+function collectBindingsInStatement(statement, scope, functionScope, reactiveAllowed) {
+  if (statement.type === "VariableDeclaration") {
+    collectBindingsFromDeclaration(
+      statement,
+      scope,
+      functionScope,
+      reactiveAllowed
+    );
+    return;
+  }
+  if (statement.type === "FunctionDeclaration") {
+    if (statement.id) scope.add(statement.id.name, false);
+    return;
+  }
+  if (statement.type === "ClassDeclaration") {
+    if (statement.id) scope.add(statement.id.name, false);
+    return;
+  }
+  if (statement.type === "ExportNamedDeclaration" && statement.declaration) {
+    collectBindingsInStatement(
+      statement.declaration,
+      scope,
+      functionScope,
+      reactiveAllowed
+    );
+  }
+  if (statement.type === "ExportDefaultDeclaration" && statement.declaration) {
+    const declaration = statement.declaration;
+    if ((declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration") && declaration.id) {
+      scope.add(declaration.id.name, false);
+    }
+  }
+}
+function collectBindingsFromDeclaration(declaration, scope, functionScope, reactiveAllowed) {
+  const isVar = declaration.kind === "var";
+  const isLet = declaration.kind === "let";
+  for (const declarator of declaration.declarations) {
+    const { names, supported } = collectPatternIdentifiers(declarator.id);
+    const reactive = isLet && reactiveAllowed && supported;
+    const targetScope = isVar ? functionScope : scope;
+    for (const name of names) {
+      targetScope.add(name, reactive);
+    }
+  }
+}
+function addFunctionBindings(node, scope) {
+  if (node.type !== "ArrowFunctionExpression" && node.id) {
+    scope.add(node.id.name, false);
+  }
+  for (const param of node.params ?? []) {
+    const { names } = collectPatternIdentifiers(param);
+    for (const name of names) {
+      scope.add(name, false);
+    }
+  }
+}
+function collectPatternIdentifiers(pattern) {
+  const names = [];
+  let supported = true;
+  const visit = (node) => {
+    if (!node) return;
+    switch (node.type) {
+      case "Identifier":
+        names.push(node.name);
+        return;
+      case "ObjectPattern":
+        for (const property of node.properties ?? []) {
+          if (property.type === "Property") {
+            visit(property.value);
+          } else if (property.type === "RestElement") {
+            visit(property.argument);
+          } else {
+            supported = false;
+          }
+        }
+        return;
+      case "ArrayPattern":
+        for (const element of node.elements ?? []) {
+          if (element) visit(element);
+        }
+        return;
+      case "AssignmentPattern":
+        visit(node.left);
+        return;
+      case "RestElement":
+        visit(node.argument);
+        return;
+      default:
+        supported = false;
+    }
+  };
+  visit(pattern);
+  return { names, supported };
+}
+function uniqueAlias(base, used) {
+  if (!used.has(base)) return base;
+  let i = 1;
+  while (used.has(`${base}_${i}`)) i += 1;
+  return `${base}_${i}`;
+}
+function injectSignalImport(s, code, alias) {
+  const statement = `import { signal as ${alias} } from "@preact/signals";
+`;
+  if (code.startsWith("#!")) {
+    const lineEnd = code.indexOf("\n");
+    if (lineEnd === -1) {
+      s.appendRight(code.length, `
+${statement}`);
+    } else {
+      s.appendLeft(lineEnd + 1, statement);
+    }
+    return;
+  }
+  s.prepend(statement);
+}
+function getIndent(code, pos) {
+  let i = pos;
+  while (i > 0 && code[i - 1] !== "\n" && code[i - 1] !== "\r") i -= 1;
+  let indent = "";
+  while (i < code.length && (code[i] === " " || code[i] === "	")) {
+    indent += code[i];
+    i += 1;
+  }
+  return indent;
+}
+function isReactiveScope(state) {
+  return state.functionDepth === 0 && state.loopDepth === 0;
+}
+function hasRange(node) {
+  return !!node && typeof node.start === "number" && typeof node.end === "number";
+}
+function warn(id, message) {
+  const prefix = id ? `[preact-alchemy] ${id}:` : "[preact-alchemy]";
+  console.warn(`${prefix} ${message}`);
+}
+
+export {
+  transform
+};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { SourceMap } from 'magic-string';
+
+type TransformResult = {
+    code: string;
+    map?: SourceMap;
+};
+declare function transform(code: string, id?: string): TransformResult;
+
+export { transform };

package/dist/index.js

@@ -0,0 +1,6 @@
+import {
+  transform
+} from "./chunk-JSNOUUYJ.js";
+export {
+  transform
+};

package/dist/vite.d.ts

@@ -0,0 +1,5 @@
+import { Plugin } from 'vite';
+
+declare function preactAlchemy(): Plugin;
+
+export { preactAlchemy as default };

package/dist/vite.js

@@ -0,0 +1,25 @@
+import {
+  transform
+} from "./chunk-JSNOUUYJ.js";
+
+// src/vite.ts
+var defaultInclude = /\.(?:mjs|cjs|js|jsx|mts|cts|ts|tsx)$/;
+function preactAlchemy() {
+  return {
+    name: "preact-alchemy",
+    enforce: "post",
+    transform(code, id) {
+      if (id.startsWith("\0")) return null;
+      const cleanId = id.split("?")[0];
+      if (!defaultInclude.test(cleanId)) return null;
+      if (cleanId.includes("node_modules")) return null;
+      if (!code.includes("use alchemy")) return null;
+      const result = transform(code, cleanId);
+      if (result.code === code) return null;
+      return { code: result.code, map: result.map ?? null };
+    }
+  };
+}
+export {
+  preactAlchemy as default
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "preact-alchemy",
+  "type": "module",
+  "version": "1.0.0",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "author": "Alec Larson",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aleclarson/preact-alchemy.git"
+  },
+  "prettier": "@alloc/prettier-config",
+  "dependencies": {
+    "magic-string": "^0.30.21",
+    "meriyah": "^7.0.0",
+    "zimmerframe": "^1.1.4"
+  },
+  "peerDependencies": {
+    "@preact/signals": "*",
+    "preact": "*"
+  },
+  "devDependencies": {
+    "@alloc/prettier-config": "^1.0.0",
+    "@preact/signals": "^2.5.1",
+    "@types/node": "^25.0.3",
+    "preact": "^10.28.0",
+    "prettier": "^3.7.4",
+    "radashi": "^12.7.1",
+    "rimraf": "^6.1.2",
+    "tsc-lint": "^0.1.9",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16"
+  },
+  "scripts": {
+    "dev": "rimraf dist && tsup --sourcemap --watch",
+    "build": "rimraf dist && tsup",
+    "format": "prettier --write .",
+    "lint": "tsc-lint",
+    "test": "vitest"
+  }
+}

package/readme.md

@@ -0,0 +1,153 @@
+# preact-alchemy
+
+A tiny transform that turns `let` bindings into @preact/signals when you opt in with a "use alchemy" directive.
+It lets you write normal JS and get reactive updates without manual `.value` plumbing.
+
+## Install
+
+```sh
+pnpm add preact-alchemy
+```
+
+## Quick start
+
+Add the directive as the first statement inside a function body:
+
+```js
+function counter() {
+  'use alchemy'
+  let count = 0
+  count += 1
+  return count
+}
+```
+
+This is rewritten to:
+
+```js
+import { signal as __alchemy_signal } from '@preact/signals'
+function counter() {
+  let count = __alchemy_signal(0)
+  count.value += 1
+  return count.value
+}
+```
+
+## How it works
+
+When a function body starts with the string literal directive `"use alchemy"`, the transform:
+
+- Rewrites `let` declarations in that function into signals.
+- Rewrites reads/writes of those bindings to use `.value`.
+- Projects object literal shorthands that reference reactive bindings.
+- Injects `import { signal as __alchemy_signal } from "@preact/signals";` when needed.
+
+### Scope rules
+
+Only `let` **declarations** are restricted: `let` declarations inside loops or nested functions are
+_not_ converted into signals. Reads and writes of a reactive binding remain reactive anywhere it is
+in scope, including inside loops and nested functions.
+
+```js
+function demo() {
+  'use alchemy'
+  let count = 0 // becomes a signal
+
+  for (let i = 0; i < 2; i++) {
+    count++ // reactive read/write
+    let local = 0 // NOT converted
+  }
+
+  function inner() {
+    count++ // reactive read/write
+    let local = 0 // NOT converted
+  }
+}
+```
+
+### Object literal projection
+
+Shorthand properties referencing a reactive binding are rewritten so you don’t leak signals by accident:
+
+```js
+return { count }
+```
+
+- At the top level: becomes a getter so reads stay reactive.
+- Inside loops/nested functions: becomes an eager value.
+
+```js
+return {
+  get count() {
+    return count.value
+  },
+}
+// or
+return { count: count.value }
+```
+
+### Destructuring
+
+Destructuring `let` declarations are supported. Each extracted name becomes a signal:
+
+```js
+let { a, b } = obj
+// ->
+let { a, b } = obj
+a = __alchemy_signal(a)
+b = __alchemy_signal(b)
+```
+
+## Vite plugin
+
+Use the built-in Vite plugin for zero-config integration:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import preactAlchemy from 'preact-alchemy/vite'
+
+export default defineConfig({
+  plugins: [preactAlchemy()],
+})
+```
+
+The plugin:
+
+- Runs on `.js/.jsx/.mjs/.cjs/.ts/.tsx/.mts/.cts` files, after Vite compiles
+  TypeScript to JavaScript.
+- Skips files in `node_modules`.
+- Only transforms files that include the `"use alchemy"` directive.
+
+## Programmatic API
+
+```ts
+import { transform } from 'preact-alchemy'
+
+const result = transform(code, id)
+console.log(result.code)
+console.log(result.map) // Source map if changes were made
+```
+
+### `transform(code, id?)`
+
+- `code`: string input source.
+- `id`: optional file name for warnings and source maps.
+- Returns `{ code, map? }`.
+
+## Limitations
+
+- JavaScript + JSX only. TypeScript/Flow syntax is **not** supported and is
+  skipped with a warning. TypeScript is supported only after compilation to
+  JavaScript (for example, via the Vite plugin).
+- Only `let` declarations are converted to signals. `const` and `var` are left untouched.
+- The directive must be the **first statement** in the function body.
+
+## Tips
+
+- You can keep normal JS semantics and sprinkle reactivity only where needed.
+- If you already use a `__alchemy_signal` variable, the import is auto-aliased.
+
+## License
+
+MIT