@firsthandjs/compiler 0.7.1 → 0.9.0

package/dist/{chunk-7DU5USN7.js → chunk-ACKKPAGI.js}

@@ -86,22 +86,49 @@ function eventName(attribute) {
 
 // packages/compiler/src/transform.ts
 var RUNTIME = "@firsthandjs/dom/internal";
+var SERVER_RUNTIME = "@firsthandjs/server/internal";
 var CORE = "@firsthandjs/core";
+var CHILD_THUNK = /* @__PURE__ */ Symbol("firsthand.childThunk");
+var GENERATED = /* @__PURE__ */ Symbol("firsthand.generated");
+function generated(arrow) {
+  arrow[GENERATED] = true;
+  return arrow;
+}
+function pushOnce(build, statement) {
+  build.once.push(statement);
+}
+function pushEach(build, statement) {
+  build.each.push(statement);
+}
 function firsthandPlugin(_api, options = {}) {
   return {
     name: "firsthand",
     visitor: {
       Program: {
-        enter(_path, state) {
+        enter(path, state) {
           state.firsthand = {
             imports: /* @__PURE__ */ new Map(),
             templates: [],
             counter: 0,
-            moduleId: stableId(options.packageName ?? "app", state.filename ?? "module")
+            moduleId: stableId(options.packageName ?? "app", state.filename ?? "module"),
+            views: /* @__PURE__ */ new Map(),
+            viewNodes: /* @__PURE__ */ new Set(),
+            runs: /* @__PURE__ */ new Map(),
+            ssr: options.ssr === true,
+            hydratable: options.hydratable === true && options.ssr !== true
           };
+          collectViews(path, state);
+          if (options.ssr !== true) {
+            collectRuns(path, state);
+          }
         },
         exit(path, state) {
-          const { imports, templates } = state.firsthand;
+          const { imports, templates, views } = state.firsthand;
+          for (const [, local] of views) {
+            path.node.body.push(
+              expressionStatement2(t.callExpression(runtime(state, "view"), [t.cloneNode(local)]))
+            );
+          }
           if (templates.length > 0) {
             path.node.body.unshift(t.variableDeclaration("const", templates));
           }
@@ -120,18 +147,22 @@ function firsthandPlugin(_api, options = {}) {
       // component's children, a dynamic expression) are re-visited later, by
       // which time they are no longer inside JSX.
       JSXElement(path, state) {
-        rewriteKeyedMaps(path, state);
+        if (!state.firsthand.ssr) {
+          rewriteKeyedMaps(path, state);
+        }
         path.replaceWith(compileNode(path, state));
       },
       JSXFragment(path, state) {
-        rewriteKeyedMaps(path, state);
+        if (!state.firsthand.ssr) {
+          rewriteKeyedMaps(path, state);
+        }
         path.replaceWith(compileNode(path, state));
       },
       CallExpression(path, state) {
         annotateComponent(path, state, options);
       },
       VariableDeclarator(path, state) {
-        if (options.devtools === true) {
+        if (options.devtools === true && options.ssr !== true) {
           nameCell(path, state);
         }
       }
@@ -153,7 +184,10 @@ function groupBySource(imports) {
   }
   return grouped;
 }
-function runtime(state, name, source = RUNTIME) {
+function runtime(state, name, source) {
+  return runtimeFrom(state, name, source ?? (state.firsthand.ssr ? SERVER_RUNTIME : RUNTIME));
+}
+function runtimeFrom(state, name, source) {
   const key = `${source}#${name}`;
   let local = state.firsthand.imports.get(key);
   if (local === void 0) {
@@ -181,6 +215,7 @@ function annotateComponent(path, state, options) {
     const setupPath = path.get("arguments.0");
     checkKeptReads(setupPath, name);
     checkDecidedOnce(setupPath, name);
+    checkRunBody(setupPath, name);
   }
   path.node.arguments = [
     setup,
@@ -220,9 +255,13 @@ function checkDecidedOnce(setup, name) {
     throw at.buildCodeFrameError(
       `${name}: this view is chosen once, here, from a value that changes. A setup runs one time per instance, so the other branch will never appear.
 
-Put the choice inside the markup, where it is a part that can run again:
+Either put the choice inside the markup, where it is a part:
 
-  return <>{open.value ? <A /> : <B />}</>;`
+  return <>{open.value ? <A /> : <B />}</>;
+
+or return a render function, which is a reactive scope of its own and may use ordinary control flow:
+
+  return () => (open.value ? <A /> : <B />);`
     );
   };
   const check = (returned, at) => {
@@ -274,6 +313,106 @@ Put the choice inside the markup, where it is a part that can run again:
     }
   });
 }
+function checkRunBody(setup, name) {
+  const runs = [];
+  const body = setup.get("body");
+  body.traverse({
+    Function(nested) {
+      nested.skip();
+    },
+    ReturnStatement(statement) {
+      const argument = statement.get("argument");
+      if (argument.isArrowFunctionExpression() || argument.isFunctionExpression()) {
+        runs.push(argument);
+      }
+    }
+  });
+  for (const run of runs) {
+    checkNothingPersistent(run, name);
+    checkRepeatedMarkup(run, name);
+  }
+}
+var PERSISTENT = /* @__PURE__ */ new Map([
+  ["signal", "a signal"],
+  ["computed", "a computed"],
+  ["effect", "an effect"],
+  ["deepSignal", "a deep signal"],
+  ["useResource", "a resource"],
+  ["useAction", "an action"],
+  ["onCleanup", "a cleanup"],
+  ["provide", "a context value"]
+]);
+function checkNothingPersistent(run, name) {
+  run.traverse({
+    Function(nested) {
+      nested.skip();
+    },
+    CallExpression(call) {
+      const callee = call.node.callee;
+      if (!t.isIdentifier(callee)) {
+        return;
+      }
+      const what = PERSISTENT.get(callee.name);
+      if (what === void 0) {
+        return;
+      }
+      const binding = call.scope.getBinding(callee.name);
+      if (binding === void 0 || !isFirsthandImport(binding)) {
+        return;
+      }
+      throw call.buildCodeFrameError(
+        `${name}: this render function makes ${what}, and it runs again whenever something it read changes \u2014 so this would be made again, and the one before it thrown away.
+
+Move it into the setup, above the render function. Persistent things are made once, where the setup runs once.`
+      );
+    }
+  });
+}
+function checkRepeatedMarkup(run, name) {
+  const report = (at) => {
+    throw at.buildCodeFrameError(
+      `${name}: this markup is written once and appears many times, so where it stands cannot say which of them is which.
+
+Give it a key:
+
+  {rows.map((row) => <Row key={row.id} row={row} />)}`
+    );
+  };
+  run.traverse({
+    Function(nested) {
+      nested.skip();
+    },
+    "ForStatement|ForOfStatement|ForInStatement|WhileStatement|DoWhileStatement"(loop) {
+      loop.traverse({
+        JSXElement(element) {
+          element.skip();
+          if (!hasKey(element.node)) {
+            report(element);
+          }
+        }
+      });
+    },
+    CallExpression(call) {
+      const callee = call.node.callee;
+      if (LIST_CALL in call.node || !t.isMemberExpression(callee) || callee.computed || !t.isIdentifier(callee.property, { name: "map" })) {
+        return;
+      }
+      call.traverse({
+        JSXElement(element) {
+          element.skip();
+          if (!hasKey(element.node)) {
+            report(element);
+          }
+        }
+      });
+    }
+  });
+}
+function hasKey(element) {
+  return element.openingElement.attributes.some(
+    (attribute) => t.isJSXAttribute(attribute) && attributeName(attribute) === "key"
+  );
+}
 function returnsView(node) {
   if (node === null || node === void 0) {
     return false;
@@ -497,7 +636,229 @@ function compileNode(path, state) {
   if (isComponentTag(node)) {
     return compileComponent(path, state);
   }
-  return compileTemplate(path, state);
+  return state.firsthand.ssr ? compileMarkup(path, state) : compileTemplate(path, state);
+}
+function collectViews(program, state) {
+  const { views, viewNodes } = state.firsthand;
+  const record = (path) => {
+    let fn = path.getFunctionParent();
+    while (fn !== null) {
+      viewNodes.add(fn.node);
+      const named = moduleLevelName(fn);
+      if (named !== null) {
+        views.set(named, t.identifier(named));
+      }
+      fn = fn.getFunctionParent();
+    }
+  };
+  program.traverse({
+    JSXElement: record,
+    JSXFragment: record
+  });
+}
+function moduleLevelName(fn) {
+  if (fn.isFunctionDeclaration()) {
+    const id = fn.node.id;
+    if (id === null || id === void 0) {
+      return null;
+    }
+    return t.isProgram(fn.parentPath.scope.block) ? id.name : null;
+  }
+  const declarator = fn.parentPath;
+  if (!declarator.isVariableDeclarator() || !t.isIdentifier(declarator.node.id)) {
+    return null;
+  }
+  return t.isProgram(declarator.scope.block) ? declarator.node.id.name : null;
+}
+function isLocalView(path, state) {
+  const name = path.node.openingElement.name;
+  if (!t.isJSXIdentifier(name)) {
+    return false;
+  }
+  const binding = path.scope.getBinding(name.name);
+  if (binding === void 0 || binding.kind === "module" || binding.constantViolations.length > 0) {
+    return false;
+  }
+  if (binding.path.isFunctionDeclaration()) {
+    return state.firsthand.viewNodes.has(binding.path.node);
+  }
+  if (!binding.path.isVariableDeclarator()) {
+    return false;
+  }
+  const init = binding.path.node.init;
+  if (!t.isArrowFunctionExpression(init) && !t.isFunctionExpression(init)) {
+    return false;
+  }
+  return state.firsthand.viewNodes.has(init);
+}
+function collectRuns(program, state) {
+  program.traverse({
+    CallExpression(call) {
+      if (!isComponentCall(call)) {
+        return;
+      }
+      const setup = call.get("arguments.0");
+      if (!setup.isArrowFunctionExpression() && !setup.isFunctionExpression()) {
+        return;
+      }
+      const found = [];
+      const body = setup.get("body");
+      if (!body.isBlockStatement()) {
+        if (body.isArrowFunctionExpression() || body.isFunctionExpression()) {
+          found.push(body);
+        }
+      } else {
+        body.traverse({
+          // A handler or a callback returns its own things; only what the
+          // setup itself hands back is the view.
+          Function(nested) {
+            nested.skip();
+          },
+          ReturnStatement(statement) {
+            const argument = statement.get("argument");
+            if (argument.isArrowFunctionExpression() || argument.isFunctionExpression()) {
+              found.push(argument);
+            }
+          }
+        });
+      }
+      if (found.length === 0) {
+        return;
+      }
+      setup.ensureBlock();
+      const block = setup.get("body");
+      for (const run of found) {
+        const store = setup.scope.generateUidIdentifier("store");
+        block.unshiftContainer(
+          "body",
+          t.variableDeclaration("const", [
+            t.variableDeclarator(
+              store,
+              t.callExpression(runtime(state, "store"), [t.stringLiteral(declaredName(call))])
+            )
+          ])
+        );
+        let index = 0;
+        state.firsthand.runs.set(run.node, {
+          node: run.node,
+          store,
+          next: () => index++
+        });
+        closeRun(run, store, state);
+      }
+    }
+  });
+}
+function closeRun(run, store, state) {
+  const body = run.get("body");
+  if (!body.isBlockStatement()) {
+    body.replaceWith(
+      t.callExpression(runtime(state, "ran"), [t.cloneNode(store), body.node])
+    );
+    return;
+  }
+  const returns = [];
+  body.traverse({
+    Function(nested) {
+      nested.skip();
+    },
+    ReturnStatement(statement) {
+      returns.push(statement);
+    }
+  });
+  for (const statement of returns) {
+    statement.node.argument = t.callExpression(runtime(state, "ran"), [
+      t.cloneNode(store),
+      statement.node.argument ?? t.identifier("undefined")
+    ]);
+  }
+}
+function isComponentCall(path) {
+  if (!t.isIdentifier(path.node.callee, { name: "component" })) {
+    return false;
+  }
+  const binding = path.scope.getBinding("component");
+  return binding !== void 0 && isFirsthandImport(binding);
+}
+function enclosingRun(path, state) {
+  let fn = path.getFunctionParent();
+  while (fn !== null && GENERATED in fn.node) {
+    fn = fn.getFunctionParent();
+  }
+  if (fn === null) {
+    return null;
+  }
+  return state.firsthand.runs.get(fn.node) ?? null;
+}
+function dependsOnRun(node, run, at) {
+  if (run === null) {
+    return false;
+  }
+  const names = /* @__PURE__ */ new Set();
+  collectNames(node, names);
+  for (const name of names) {
+    const binding = at.scope.getBinding(name);
+    if (binding === void 0) {
+      continue;
+    }
+    if (binding.scope.block === run.node || binding.path.findParent((parent) => parent.node === run.node) !== null) {
+      return true;
+    }
+  }
+  return false;
+}
+function collectNames(node, into) {
+  if (t.isIdentifier(node)) {
+    into.add(node.name);
+    return;
+  }
+  for (const key of t.VISITOR_KEYS[node.type]) {
+    if (t.isMemberExpression(node) && !node.computed && key === "property") {
+      continue;
+    }
+    if ((t.isObjectProperty(node) || t.isObjectMethod(node)) && !node.computed && key === "key") {
+      continue;
+    }
+    const value = node[key];
+    for (const child of Array.isArray(value) ? value : [value]) {
+      if (typeof child === "object" && child !== null) {
+        collectNames(child, into);
+      }
+    }
+  }
+}
+function canRetain(node, build) {
+  let possible = true;
+  const visit = (element) => {
+    for (const attribute of element.openingElement.attributes) {
+      if (t.isJSXSpreadAttribute(attribute)) {
+        if (dependsOnRun(attribute.argument, build.run, build.at)) {
+          possible = false;
+        }
+        continue;
+      }
+      const value = attribute.value;
+      if (attributeName(attribute) === "ref" && t.isJSXExpressionContainer(value) && !t.isJSXEmptyExpression(value.expression) && dependsOnRun(value.expression, build.run, build.at)) {
+        possible = false;
+      }
+    }
+    for (const child of element.children) {
+      if (t.isJSXElement(child)) {
+        if (!isComponentTag(child)) {
+          visit(child);
+        }
+        continue;
+      }
+      if (t.isJSXExpressionContainer(child) && !t.isJSXEmptyExpression(child.expression) && isKeyedList(child.expression) && dependsOnRun(child.expression, build.run, build.at)) {
+        possible = false;
+      }
+    }
+  };
+  visit(node);
+  return possible;
+}
+function isKeyedList(node) {
+  return t.isCallExpression(node) && LIST_CALL in node;
 }
 function isComponentTag(node) {
   const name = node.openingElement.name;
@@ -517,7 +878,25 @@ function tagExpression(name) {
 }
 function compileComponent(path, state) {
   const node = path.node;
+  const run = enclosingRun(path, state);
   const properties = [];
+  const cells = [];
+  const throughCell = (value) => {
+    const holder = t.identifier(`_cell$${String(run.next())}`);
+    cells.push(
+      t.variableDeclaration("const", [
+        t.variableDeclarator(
+          holder,
+          t.callExpression(runtime(state, "cell"), [
+            t.cloneNode(run.store),
+            t.numericLiteral(run.next()),
+            value
+          ])
+        )
+      ])
+    );
+    return t.memberExpression(t.cloneNode(holder), t.identifier("value"));
+  };
   for (const attribute of node.openingElement.attributes) {
     if (t.isJSXSpreadAttribute(attribute)) {
       properties.push(t.spreadElement(attribute.argument));
@@ -525,12 +904,20 @@ function compileComponent(path, state) {
     }
     const name = attributeName(attribute);
     const value = attributeValue(attribute);
+    if (state.firsthand.ssr && name === "key") {
+      continue;
+    }
     if (value === null || isStaticValue(value)) {
       properties.push(t.objectProperty(propertyKey(name), value ?? t.booleanLiteral(true)));
     } else {
-      properties.push(
-        t.objectMethod("get", propertyKey(name), [], t.blockStatement([t.returnStatement(value)]))
-      );
+      const held = dependsOnRun(value, run, path) ? throughCell(value) : value;
+      if (state.firsthand.ssr && isPure(value)) {
+        properties.push(t.objectProperty(propertyKey(name), held));
+      } else {
+        const read = t.returnStatement(held);
+        takePosition(read, value);
+        properties.push(t.objectMethod("get", propertyKey(name), [], t.blockStatement([read])));
+      }
     }
   }
   const children = compileChildren(node.children, state);
@@ -553,11 +940,94 @@ function compileComponent(path, state) {
       )
     );
   }
-  return t.callExpression(runtime(state, "createComponent"), [
-    // `isComponentTag` has already excluded namespaced names.
-    tagExpression(node.openingElement.name),
-    t.objectExpression(properties)
-  ]);
+  const tag = tagExpression(node.openingElement.name);
+  const make = isLocalView(path, state) ? t.callExpression(tag, [t.objectExpression(properties)]) : t.callExpression(runtime(state, "createComponent"), [tag, t.objectExpression(properties)]);
+  if (run !== null) {
+    return keptChild(state, run, make, cells);
+  }
+  if (isLocalView(path, state)) {
+    if (state.firsthand.ssr) {
+      return make;
+    }
+    const parent = path.parentPath;
+    if (parent.isArrowFunctionExpression() && parent.node.body === node && CHILD_THUNK in parent.node) {
+      return make;
+    }
+    return t.callExpression(runtime(state, "part"), [t.arrowFunctionExpression([], make)]);
+  }
+  return make;
+}
+function keptChild(state, run, make, cells) {
+  const slot = t.identifier(`_kept$${String(run.next())}`);
+  const held = t.identifier(`_own$${String(run.next())}`);
+  const made = () => t.memberExpression(t.cloneNode(slot), t.identifier("last"));
+  const body = [
+    ...cells,
+    t.variableDeclaration("const", [
+      t.variableDeclarator(
+        slot,
+        t.callExpression(runtime(state, "site"), [
+          t.cloneNode(run.store),
+          t.numericLiteral(run.next())
+        ])
+      )
+    ]),
+    t.ifStatement(
+      t.binaryExpression("===", made(), t.identifier("undefined")),
+      t.blockStatement([
+        t.variableDeclaration("const", [
+          t.variableDeclarator(
+            held,
+            t.callExpression(runtime(state, "open"), [t.cloneNode(run.store), t.cloneNode(slot)])
+          )
+        ]),
+        expressionStatement2(
+          t.assignmentExpression(
+            "=",
+            made(),
+            t.callExpression(runtime(state, "part"), [t.arrowFunctionExpression([], make)])
+          )
+        ),
+        expressionStatement2(t.callExpression(runtime(state, "close"), [t.cloneNode(held)]))
+      ])
+    ),
+    t.returnStatement(made())
+  ];
+  return t.callExpression(generated(t.arrowFunctionExpression([], t.blockStatement(body))), []);
+}
+function isPure(node) {
+  switch (node.type) {
+    case "Identifier":
+    case "ThisExpression":
+    case "StringLiteral":
+    case "NumericLiteral":
+    case "BooleanLiteral":
+    case "NullLiteral":
+    case "BigIntLiteral":
+    case "RegExpLiteral":
+      return true;
+    case "MemberExpression":
+    case "OptionalMemberExpression":
+      return isPure(node.object) && (!node.computed || isPure(node.property));
+    case "UnaryExpression":
+      return node.operator !== "delete" && isPure(node.argument);
+    case "BinaryExpression":
+      return isPure(node.left) && isPure(node.right);
+    case "LogicalExpression":
+      return isPure(node.left) && isPure(node.right);
+    case "ConditionalExpression":
+      return isPure(node.test) && isPure(node.consequent) && isPure(node.alternate);
+    case "TemplateLiteral":
+      return node.expressions.every((one) => t.isExpression(one) && isPure(one));
+    case "ArrayExpression":
+      return node.elements.every((one) => one === null || t.isExpression(one) && isPure(one));
+    case "ObjectExpression":
+      return node.properties.every(
+        (one) => t.isObjectProperty(one) && !one.computed && t.isExpression(one.value) && isPure(one.value)
+      );
+    default:
+      return false;
+  }
 }
 function propertyKey(name) {
   return t.isValidIdentifier(name) ? t.identifier(name) : t.stringLiteral(name);
@@ -582,15 +1052,149 @@ function attributeValue(attribute) {
 function isStaticValue(value) {
   return t.isStringLiteral(value) || t.isNumericLiteral(value) || t.isBooleanLiteral(value) || t.isNullLiteral(value);
 }
+function pushText(markup, text) {
+  markup.parts[markup.parts.length - 1] = markup.parts[markup.parts.length - 1] + text;
+}
+function pushHole(markup, value) {
+  markup.values.push(value);
+  markup.parts.push("");
+}
+function compileMarkup(path, state) {
+  const markup = { parts: [""], values: [] };
+  emitMarkupElement(path.node, markup, state);
+  if (markup.values.length === 0) {
+    return t.callExpression(runtime(state, "ssr"), [
+      t.arrayExpression([t.stringLiteral(markup.parts[0])])
+    ]);
+  }
+  return t.callExpression(runtime(state, "ssr"), [
+    t.arrayExpression(markup.parts.map((part) => t.stringLiteral(part))),
+    ...markup.values
+  ]);
+}
+function emitMarkupElement(node, markup, state) {
+  const name = node.openingElement.name;
+  if (!t.isJSXIdentifier(name)) {
+    const namespaced = name;
+    throw new Error(
+      `Namespaced element names are not supported: <${namespaced.namespace.name}:${namespaced.name.name}>. Write the element without a namespace; SVG children are resolved by the parser.`
+    );
+  }
+  const tag = name.name;
+  pushText(markup, `<${tag}`);
+  for (const attribute of node.openingElement.attributes) {
+    emitMarkupAttribute(attribute, markup, state);
+  }
+  pushText(markup, ">");
+  emitMarkupChildren(node.children, markup, state);
+  if (!VOID_ELEMENTS.has(tag)) {
+    pushText(markup, `</${tag}>`);
+  }
+}
+function emitMarkupAttribute(attribute, markup, state) {
+  if (t.isJSXSpreadAttribute(attribute)) {
+    pushHole(markup, t.callExpression(runtime(state, "spread"), [attribute.argument]));
+    return;
+  }
+  const name = attributeName(attribute);
+  const value = attributeValue(attribute);
+  if (name === "ref" || name.startsWith("on") && name.length > 2 && /[A-Z:]/.test(name[2])) {
+    return;
+  }
+  if (name === "key") {
+    return;
+  }
+  if (value === null) {
+    pushText(markup, ` ${name}=""`);
+    return;
+  }
+  if (isStaticValue(value)) {
+    if (t.isBooleanLiteral(value) && !value.value) {
+      return;
+    }
+    if (t.isNullLiteral(value)) {
+      return;
+    }
+    const literal = t.isStringLiteral(value) ? value.value : t.isNumericLiteral(value) ? String(value.value) : "";
+    pushText(markup, ` ${name}="${escapeAttribute(literal)}"`);
+    return;
+  }
+  pushHole(markup, markupAttributeCall(name, value, state));
+}
+function markupAttributeCall(name, value, state) {
+  if (name.startsWith("prop:")) {
+    return t.callExpression(runtime(state, "setProperty"), [t.stringLiteral(name.slice(5)), value]);
+  }
+  if (name.startsWith("attr:")) {
+    return t.callExpression(runtime(state, "setAttribute"), [
+      t.stringLiteral(name.slice(5)),
+      value
+    ]);
+  }
+  if (name === "class" || name === "className") {
+    return t.callExpression(runtime(state, "setClass"), [value]);
+  }
+  if (name === "style") {
+    return t.callExpression(runtime(state, "setStyle"), [value]);
+  }
+  if (BOOLEAN_PROPERTIES.has(name)) {
+    return t.callExpression(runtime(state, "setBoolean"), [t.stringLiteral(name), value]);
+  }
+  if (DOM_PROPERTIES.has(name)) {
+    return t.callExpression(runtime(state, "setProperty"), [t.stringLiteral(name), value]);
+  }
+  return t.callExpression(runtime(state, "setAttribute"), [t.stringLiteral(name), value]);
+}
+function emitMarkupChildren(children, markup, state) {
+  const entries = planChildren(children);
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.kind === "text") {
+      pushText(markup, escapeText(entry.text));
+      continue;
+    }
+    if (entry.kind === "element") {
+      emitMarkupElement(entry.element, markup, state);
+      continue;
+    }
+    if (entries.length > 1) {
+      pushText(markup, "<!--[-->");
+    }
+    pushHole(markup, t.callExpression(runtime(state, "child"), [entry.expression]));
+    if (i !== entries.length - 1) {
+      pushText(markup, "<!---->");
+    }
+  }
+}
 function compileTemplate(path, state) {
+  let names = 0;
+  const statements = [];
   const build = {
     html: [],
-    statements: [],
+    statements,
+    // Where a site is built once, these are three lists; where it is not, they
+    // are one, and everything simply happens in the order it was written.
+    once: statements,
+    each: statements,
+    run: null,
+    at: path,
     next: /* @__PURE__ */ (() => {
       let n = 0;
       return () => t.identifier(`_el$${String(++n)}`);
-    })()
+    })(),
+    name: (prefix) => t.identifier(`${prefix}${String(++names)}`)
   };
+  const run = enclosingRun(path, state);
+  if (run !== null) {
+    build.run = run;
+    if (canRetain(path.node, build)) {
+      build.once = [];
+      build.each = [];
+    } else {
+      build.run = null;
+    }
+  }
+  const kept = build.run !== null;
   const root = t.identifier("_el$");
   emitElement(path.node, build, root, state);
   const templateId = t.identifier(`_tmpl$${String(++state.firsthand.counter)}`);
@@ -604,14 +1208,107 @@ function compileTemplate(path, state) {
       )
     )
   );
+  if (!kept) {
+    const body2 = [
+      t.variableDeclaration("const", [
+        t.variableDeclarator(root, t.callExpression(t.cloneNode(templateId), []))
+      ]),
+      ...build.statements,
+      t.returnStatement(t.cloneNode(root))
+    ];
+    return t.callExpression(generated(t.arrowFunctionExpression([], t.blockStatement(body2))), []);
+  }
+  const slot = build.name("_site$");
+  const fresh = build.name("_new$");
+  const held = build.name("_own$");
+  const owner = build.run;
   const body = [
     t.variableDeclaration("const", [
-      t.variableDeclarator(root, t.callExpression(t.cloneNode(templateId), []))
+      t.variableDeclarator(
+        slot,
+        t.callExpression(runtime(state, "site"), [
+          t.cloneNode(owner.store),
+          t.numericLiteral(owner.next())
+        ])
+      )
+    ]),
+    t.variableDeclaration("let", [
+      t.variableDeclarator(root, t.memberExpression(t.cloneNode(slot), t.identifier("node")))
+    ]),
+    t.variableDeclaration("const", [
+      t.variableDeclarator(
+        fresh,
+        t.binaryExpression("===", t.cloneNode(root), t.identifier("undefined"))
+      )
     ]),
+    t.variableDeclaration("let", [t.variableDeclarator(held)]),
+    t.ifStatement(
+      t.cloneNode(fresh),
+      t.blockStatement([
+        // What this site makes belongs to the instance. A run's own scope is
+        // cleared before it runs again, and a part left there would be
+        // disposed by the very next run.
+        expressionStatement2(
+          t.assignmentExpression(
+            "=",
+            t.cloneNode(held),
+            t.callExpression(runtime(state, "open"), [t.cloneNode(owner.store), t.cloneNode(slot)])
+          )
+        ),
+        expressionStatement2(
+          t.assignmentExpression(
+            "=",
+            t.cloneNode(root),
+            t.assignmentExpression(
+              "=",
+              t.memberExpression(t.cloneNode(slot), t.identifier("node")),
+              t.callExpression(t.cloneNode(templateId), [])
+            )
+          )
+        )
+      ])
+    ),
     ...build.statements,
-    t.returnStatement(t.cloneNode(root))
+    t.ifStatement(
+      t.cloneNode(fresh),
+      t.blockStatement([
+        ...build.once,
+        expressionStatement2(t.callExpression(runtime(state, "close"), [t.cloneNode(held)]))
+      ])
+    )
   ];
-  return t.callExpression(t.arrowFunctionExpression([], t.blockStatement(body)), []);
+  body.push(...build.each, t.returnStatement(t.cloneNode(root)));
+  return t.callExpression(generated(t.arrowFunctionExpression([], t.blockStatement(body))), []);
+}
+function guardedWrite(build, state, value, write) {
+  const run = build.run;
+  const slot = build.name("_w$");
+  const held = build.name("_x$");
+  const last = () => t.memberExpression(t.cloneNode(slot), t.identifier("last"));
+  pushEach(
+    build,
+    t.variableDeclaration("const", [
+      t.variableDeclarator(
+        slot,
+        t.callExpression(runtime(state, "site"), [
+          t.cloneNode(run.store),
+          t.numericLiteral(run.next())
+        ])
+      ),
+      t.variableDeclarator(held, value)
+    ])
+  );
+  pushEach(
+    build,
+    t.ifStatement(
+      t.binaryExpression("!==", last(), t.cloneNode(held)),
+      t.blockStatement([
+        expressionStatement2(t.assignmentExpression("=", last(), t.cloneNode(held))),
+        expressionStatement2(t.callExpression(runtime(state, "wrote"), [t.cloneNode(run.store)])),
+        expressionStatement2(write(t.cloneNode(held)))
+      ])
+    )
+  );
 }
 function emitElement(node, build, self, state) {
   const name = node.openingElement.name;
@@ -639,7 +1336,8 @@ function emitElement(node, build, self, state) {
 function emitAttribute(attribute, build, self, state, deferred, tag) {
   if (t.isJSXSpreadAttribute(attribute)) {
     deferred.push(() => {
-      build.statements.push(
+      pushOnce(
+        build,
         expressionStatement2(
           t.callExpression(runtime(state, "bind"), [
             t.arrowFunctionExpression(
@@ -656,7 +1354,8 @@ function emitAttribute(attribute, build, self, state, deferred, tag) {
   const value = attributeValue(attribute);
   if (name === "ref") {
     deferred.push(() => {
-      build.statements.push(
+      pushOnce(
+        build,
         expressionStatement2(t.callExpression(value, [t.cloneNode(self)]))
       );
     });
@@ -680,7 +1379,12 @@ function emitAttribute(attribute, build, self, state, deferred, tag) {
           t.objectExpression([t.objectProperty(propertyKey(modifier), t.booleanLiteral(true))])
         );
       }
-      build.statements.push(expressionStatement2(t.callExpression(runtime(state, "on"), args)));
+      const attach = expressionStatement2(t.callExpression(runtime(state, "on"), args));
+      if (dependsOnRun(value, build.run, build.at)) {
+        pushEach(build, attach);
+      } else {
+        pushOnce(build, attach);
+      }
     });
     return;
   }
@@ -700,7 +1404,17 @@ function emitAttribute(attribute, build, self, state, deferred, tag) {
     return;
   }
   deferred.push(() => {
-    build.statements.push(
+    if (dependsOnRun(value, build.run, build.at)) {
+      guardedWrite(
+        build,
+        state,
+        value,
+        (held) => dynamicAttributeCall(name, held, self, state, tag)
+      );
+      return;
+    }
+    pushOnce(
+      build,
       expressionStatement2(
         t.callExpression(runtime(state, "bind"), [
           located(
@@ -860,7 +1574,7 @@ function emitChildren(children, build, self, state) {
     const id = build.next();
     build.statements.push(
       t.variableDeclaration("const", [
-        t.variableDeclarator(id, navigate(self, previous, previousIndex, index))
+        t.variableDeclarator(id, navigate(self, previous, previousIndex, index, state))
       ])
     );
     previous = id;
@@ -886,18 +1600,39 @@ function emitChildren(children, build, self, state) {
       continue;
     }
     const isLast = i === entries.length - 1;
+    const expression = entry.expression;
+    let marker = null;
+    if (!isLast) {
+      build.html.push("<!>");
+      marker = t.cloneNode(reference());
+    }
+    if (entry.kind !== "list" && dependsOnRun(expression, build.run, build.at)) {
+      const run = build.run;
+      pushEach(
+        build,
+        expressionStatement2(
+          t.callExpression(runtime(state, "writeChild"), [
+            t.cloneNode(run.store),
+            t.numericLiteral(run.next()),
+            t.cloneNode(self),
+            marker ?? t.nullLiteral(),
+            expression
+          ])
+        )
+      );
+      index++;
+      continue;
+    }
     const args = [
       t.cloneNode(self),
       // A list part is already a thunk that owns its rows; wrapping it would
       // rebuild the whole list on every evaluation.
-      entry.kind === "list" ? entry.expression : thunk(entry.expression)
+      entry.kind === "list" ? expression : thunk(expression)
     ];
-    if (!isLast) {
-      build.html.push("<!>");
-      const id = reference();
-      args.push(t.cloneNode(id));
+    if (marker !== null) {
+      args.push(marker);
     }
-    build.statements.push(expressionStatement2(t.callExpression(runtime(state, "insert"), args)));
+    pushOnce(build, expressionStatement2(t.callExpression(runtime(state, "insert"), args)));
     index++;
   }
 }
@@ -925,18 +1660,21 @@ function needsReference(element) {
   }
   return false;
 }
-function navigate(self, previous, previousIndex, index) {
+function navigate(self, previous, previousIndex, index, state) {
+  const hydratable = state.firsthand.hydratable;
+  const first = hydratable ? runtime(state, "first") : null;
+  const next = hydratable ? runtime(state, "next") : null;
   let expression;
   let steps;
   if (previous === null) {
-    expression = t.memberExpression(t.cloneNode(self), t.identifier("firstChild"));
+    expression = hydratable ? t.callExpression(first, [t.cloneNode(self)]) : t.memberExpression(t.cloneNode(self), t.identifier("firstChild"));
     steps = index;
   } else {
     expression = t.cloneNode(previous);
     steps = index - previousIndex;
   }
   for (let i = 0; i < steps; i++) {
-    expression = t.memberExpression(expression, t.identifier("nextSibling"));
+    expression = hydratable ? t.callExpression(next, [expression]) : t.memberExpression(expression, t.identifier("nextSibling"));
   }
   return expression;
 }
@@ -1002,13 +1740,13 @@ function compileChildren(children, state) {
       result.push(t.stringLiteral(entry.text));
     } else if (entry.kind === "element") {
       result.push(entry.element);
+    } else if (state.firsthand.ssr) {
+      result.push(entry.expression);
     } else if (entry.kind === "list") {
       result.push(t.callExpression(runtime(state, "part"), [entry.expression]));
     } else {
       result.push(
-        t.callExpression(runtime(state, "part"), [
-          t.arrowFunctionExpression([], entry.expression)
-        ])
+        t.callExpression(runtime(state, "part"), [thunk(entry.expression)])
       );
     }
   }
@@ -1016,12 +1754,16 @@ function compileChildren(children, state) {
 }
 function thunk(expression) {
   const arrow = t.arrowFunctionExpression([], expression);
+  arrow[CHILD_THUNK] = true;
+  takePosition(arrow, expression);
+  return arrow;
+}
+function takePosition(target, expression) {
   const loc = expression.loc;
   if (loc !== null && loc !== void 0) {
-    arrow.loc = { ...loc, end: loc.start };
+    target.loc = { ...loc, end: loc.start };
     expression.loc = null;
   }
-  return arrow;
 }
 function expressionStatement2(expression) {
   return located(t.expressionStatement(expression), expression);
@@ -1070,7 +1812,9 @@ function buildPlugins(options) {
     {
       packageName: options.packageName,
       strictReactivity: options.strictReactivity,
-      devtools: options.devtools
+      devtools: options.devtools,
+      ssr: options.ssr,
+      hydratable: options.hydratable
     }
   ]);
   return plugins;

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   firsthandPlugin,
   stableId,
   transform
-} from "./chunk-7DU5USN7.js";
+} from "./chunk-ACKKPAGI.js";
 export {
   compileModule,
   firsthandPlugin,

package/dist/transform.d.ts

@@ -18,6 +18,32 @@ type FirsthandState = {
     templates: t.VariableDeclarator[];
     counter: number;
     moduleId: string;
+    /** Module-level functions markup was compiled into, in source order. */
+    views: Map<string, t.Identifier>;
+    /** Every function markup was written inside, for resolving tags locally. */
+    viewNodes: Set<t.Node>;
+    /** Whether this module is being compiled for a server render. */
+    ssr: boolean;
+    /** Whether this module's output has to be able to adopt server markup. */
+    hydratable: boolean;
+    /** Functions that run again as a whole, and where each keeps its sites. */
+    runs: Map<t.Node, RunContext>;
+};
+/**
+ * What a re-running function needs in order to keep its DOM.
+ *
+ * `store` is an array declared once per instance — in the setup, which runs
+ * once — and every site inside the run takes a numbered place in it. The index
+ * is fixed at compile time, so a site inside an `if` keeps its own place
+ * whether or not the branch was taken: nothing depends on the order the run
+ * happens to reach things in, which is the rule React needs for hooks and this
+ * does not.
+ */
+type RunContext = {
+    /** The function whose body re-runs. Bindings inside it belong to one run. */
+    node: t.Node;
+    store: t.Identifier;
+    next: () => number;
 };
 declare module '@babel/core' {
     interface PluginPass {
@@ -49,6 +75,26 @@ export type FirsthandPluginOptions = {
      * production build emits nothing.
      */
     devtools?: boolean;
+    /**
+     * Compile for a server render.
+     *
+     * The same source, emitted against `@firsthandjs/server/internal` instead of
+     * `@firsthandjs/dom/internal`: markup is built as a string rather than as
+     * nodes, and the things a server cannot do — listeners, refs, retained
+     * sites — are not emitted at all.
+     *
+     * The Vite plugin sets this from the bundler's own `ssr` flag, so an
+     * application configures nothing.
+     */
+    ssr?: boolean;
+    /**
+     * Emit navigation that can walk server markup.
+     *
+     * An application that hydrates needs it; one that does not should leave it
+     * off, because it turns two property reads per dynamic position into two
+     * calls. The Vite plugin sets it for a project that has a server build.
+     */
+    hydratable?: boolean;
 };
 export default function firsthandPlugin(_api: unknown, options?: FirsthandPluginOptions): PluginObject;
 export {};

package/dist/transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../src/transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,aAAa,CAAC;AAE5D,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAelC,KAAK,cAAc,GAAG;IACpB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;IACnC,SAAS,EAAE,CAAC,CAAC,kBAAkB,EAAE,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,OAAO,QAAQ,aAAa,CAAC;IAC3B,UAAU,UAAU;QAClB,SAAS,EAAE,cAAc,CAAC;KAC3B;CACF;AAUD,MAAM,MAAM,sBAAsB,GAAG;IACnC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,eAAe,CACrC,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,sBAA2B,GACnC,YAAY,CAsDd"}
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../src/transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,aAAa,CAAC;AAE5D,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAgBlC,KAAK,cAAc,GAAG;IACpB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;IACnC,SAAS,EAAE,CAAC,CAAC,kBAAkB,EAAE,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;IACjC,4EAA4E;IAC5E,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACvB,iEAAiE;IACjE,GAAG,EAAE,OAAO,CAAC;IACb,0EAA0E;IAC1E,UAAU,EAAE,OAAO,CAAC;IACpB,2EAA2E;IAC3E,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;GASG;AACH,KAAK,UAAU,GAAG;IAChB,6EAA6E;IAC7E,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;IACb,KAAK,EAAE,CAAC,CAAC,UAAU,CAAC;IACpB,IAAI,EAAE,MAAM,MAAM,CAAC;CACpB,CAAC;AAyBF,OAAO,QAAQ,aAAa,CAAC;IAC3B,UAAU,UAAU;QAClB,SAAS,EAAE,cAAc,CAAC;KAC3B;CACF;AA2BD,MAAM,MAAM,sBAAsB,GAAG;IACnC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;OAUG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,eAAe,CACrC,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,sBAA2B,GACnC,YAAY,CAiFd"}

package/dist/vite.d.ts

@@ -7,7 +7,9 @@ export type VitePluginLike = {
     configResolved(config: {
         command: string;
     }): void;
-    transform(code: string, id: string): {
+    transform(code: string, id: string, options?: {
+        ssr?: boolean | undefined;
+    }): {
         code: string;
         map: SourceMap | null;
     } | null;
@@ -18,5 +20,28 @@ export type VitePluginLike = {
  * Runs before the bundler's TypeScript step: Firsthand parses TS syntax but leaves
  * the annotations in place, so exactly one tool strips them.
  */
-export declare function firsthand(options?: FirsthandPluginOptions): VitePluginLike;
+export type FirsthandViteOptions = FirsthandPluginOptions & {
+    /**
+     * Files to compile. Everything with a JSX extension, by default.
+     *
+     * Patterns are regular expressions rather than globs, so that this package
+     * keeps its promise of having no dependencies — and so that what matches is
+     * something you can read rather than something you have to guess at.
+     */
+    include?: readonly RegExp[];
+    /**
+     * Files to leave alone.
+     *
+     * This is how a project says *these are not mine*: a folder of React
+     * components kept during a migration, compiled by React's own transform.
+     * What this compiler does not compile, it does not claim — a component from
+     * an excluded file reaches the adapter like any other foreign one.
+     *
+     * ```ts
+     * firsthand({ exclude: [/\/legacy\//] })
+     * ```
+     */
+    exclude?: readonly RegExp[];
+};
+export declare function firsthand(options?: FirsthandViteOptions): VitePluginLike;
 //# sourceMappingURL=vite.d.ts.map

package/dist/vite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE7D,0FAA0F;AAC1F,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,KAAK,CAAC;IACf,cAAc,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CACrF,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,sBAA2B,GAAG,cAAc,CA0B9E"}
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE7D,0FAA0F;AAC1F,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,KAAK,CAAC;IACf,cAAc,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClD,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EAIV,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;KAAE,GACtC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CACnD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,GAAG;IAC1D;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B,CAAC;AAEF,wBAAgB,SAAS,CAAC,OAAO,GAAE,oBAAyB,GAAG,cAAc,CAsC5E"}

package/dist/vite.js

@@ -1,6 +1,6 @@
 import {
   compileModule
-} from "./chunk-7DU5USN7.js";
+} from "./chunk-ACKKPAGI.js";
 
 // packages/compiler/src/vite.ts
 function firsthand(options = {}) {
@@ -11,17 +11,27 @@ function firsthand(options = {}) {
     configResolved(config) {
       serving = config.command === "serve";
     },
-    transform(code, id) {
+    transform(code, id, hook) {
       const file = id.split("?")[0];
       if (!file.endsWith(".tsx") && !file.endsWith(".jsx")) {
         return null;
       }
+      if (options.exclude?.some((pattern) => pattern.test(file)) === true) {
+        return null;
+      }
+      if (options.include !== void 0 && !options.include.some((pattern) => pattern.test(file))) {
+        return null;
+      }
       return compileModule(code, {
         filename: file,
         typescript: file.endsWith(".tsx"),
         devtools: serving,
         sourceMaps: true,
-        ...options
+        ...options,
+        // The bundler already knows which build this is. An explicit `ssr`
+        // option still wins, because a project that compiles a module by hand
+        // has its own reasons.
+        ssr: options.ssr ?? hook?.ssr === true
       });
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firsthandjs/compiler",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Build-time TSX transform for Firsthand: static markup into templates, dynamic expressions into DOM parts.",
   "license": "MIT",
   "type": "module",