@fictjs/compiler 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -14279,6 +14279,35 @@ var SAFE_FUNCTIONS = /* @__PURE__ */ new Set([
   "Date.parse"
 ]);
 
+// src/debug.ts
+function parseFlag(raw) {
+  if (!raw) return false;
+  const val = raw.toLowerCase();
+  return val === "1" || val === "true" || val === "yes" || val === "on";
+}
+function debugEnabled(flag) {
+  const normalized = flag.toLowerCase();
+  const legacy = process.env[`DEBUG_${flag.toUpperCase()}`];
+  if (parseFlag(legacy)) return true;
+  const fictLegacy = process.env[`FICT_DEBUG_${flag.toUpperCase()}`];
+  if (parseFlag(fictLegacy)) return true;
+  const raw = process.env.FICT_DEBUG ?? process.env.DEBUG_FICT;
+  if (!raw) return false;
+  if (parseFlag(raw)) return true;
+  const parts = raw.split(",").map((p) => p.trim().toLowerCase()).filter(Boolean);
+  return parts.includes(normalized) || parts.includes("all");
+}
+function debugLog(flag, message, data) {
+  if (!debugEnabled(flag)) return;
+  const msg = typeof message === "function" ? message() : message;
+  const prefix = `[fict:${flag}]`;
+  if (data !== void 0) {
+    console.log(prefix, msg, data);
+  } else {
+    console.log(prefix, msg);
+  }
+}
+
 // src/ir/build-hir.ts
 var t = __toESM(require_lib3(), 1);
 
@@ -15680,7 +15709,7 @@ function convertExpression(node) {
         }
         if (t.isObjectMethod(prop)) {
           if (prop.computed) return void 0;
-          const keyExpr2 = t.isIdentifier(prop.key) ? { kind: "Identifier", name: prop.key.name } : t.isStringLiteral(prop.key) ? { kind: "Literal", value: prop.key.value } : void 0;
+          const keyExpr2 = t.isIdentifier(prop.key) ? { kind: "Identifier", name: prop.key.name } : t.isStringLiteral(prop.key) ? { kind: "Literal", value: prop.key.value } : t.isNumericLiteral(prop.key) ? { kind: "Literal", value: prop.key.value } : void 0;
           if (!keyExpr2) return void 0;
           const fnExpr = t.functionExpression(
             null,
@@ -15697,7 +15726,7 @@ function convertExpression(node) {
           };
         }
         if (!t.isObjectProperty(prop) || prop.computed) return void 0;
-        const keyExpr = t.isIdentifier(prop.key) ? { kind: "Identifier", name: prop.key.name } : t.isStringLiteral(prop.key) ? { kind: "Literal", value: prop.key.value } : void 0;
+        const keyExpr = t.isIdentifier(prop.key) ? { kind: "Identifier", name: prop.key.name } : t.isStringLiteral(prop.key) ? { kind: "Literal", value: prop.key.value } : t.isNumericLiteral(prop.key) ? { kind: "Literal", value: prop.key.value } : void 0;
         if (!keyExpr) return void 0;
         if (!t.isExpression(prop.value)) return void 0;
         return {
@@ -16039,23 +16068,6 @@ function convertJSXMemberExpr(node) {
   };
 }
 
-// src/debug.ts
-function parseFlag(raw) {
-  if (!raw) return false;
-  const val = raw.toLowerCase();
-  return val === "1" || val === "true" || val === "yes" || val === "on";
-}
-function debugEnabled(flag) {
-  const normalized = flag.toLowerCase();
-  const legacy = process.env[`DEBUG_${flag.toUpperCase()}`];
-  if (parseFlag(legacy)) return true;
-  const raw = process.env.FICT_DEBUG ?? process.env.DEBUG_FICT;
-  if (!raw) return false;
-  if (parseFlag(raw)) return true;
-  const parts = raw.split(",").map((p) => p.trim().toLowerCase()).filter(Boolean);
-  return parts.includes(normalized) || parts.includes("all");
-}
-
 // src/fine-grained-dom.ts
 function normalizeDependencyKey(name) {
   return name.split(".").map((part) => part.replace(/_\d+$/, "")).join(".");
@@ -18105,6 +18117,35 @@ function structurizeTry(ctx, block, term) {
 
 // src/ir/regions.ts
 var REACTIVE_CREATORS = /* @__PURE__ */ new Set(["createEffect", "createMemo", "createSelector"]);
+function buildEffectCall(ctx, t2, effectFn, options) {
+  if (ctx.inModule) {
+    ctx.helpersUsed.add("effect");
+    return t2.callExpression(t2.identifier(RUNTIME_ALIASES.effect), [effectFn]);
+  }
+  ctx.helpersUsed.add("useEffect");
+  ctx.needsCtx = true;
+  const args = [t2.identifier("__fictCtx"), effectFn];
+  const slot = options?.slot;
+  if (options?.forceSlot) {
+    args.push(slot !== void 0 && slot >= 0 ? t2.numericLiteral(slot) : t2.identifier("undefined"));
+  } else if (slot !== void 0 && slot >= 0) {
+    args.push(t2.numericLiteral(slot));
+  }
+  return t2.callExpression(t2.identifier(RUNTIME_ALIASES.useEffect), args);
+}
+function buildMemoCall(ctx, t2, memoFn, slot) {
+  if (ctx.inModule) {
+    ctx.helpersUsed.add("memo");
+    return t2.callExpression(t2.identifier(RUNTIME_ALIASES.memo), [memoFn]);
+  }
+  ctx.helpersUsed.add("useMemo");
+  ctx.needsCtx = true;
+  const args = [t2.identifier("__fictCtx"), memoFn];
+  if (slot !== void 0 && slot >= 0) {
+    args.push(t2.numericLiteral(slot));
+  }
+  return t2.callExpression(t2.identifier(RUNTIME_ALIASES.useMemo), args);
+}
 function expressionCreatesReactive(expr) {
   if (expr.kind === "CallExpression" && expr.callee.kind === "Identifier") {
     const base = getSSABaseName(expr.callee.name);
@@ -18395,8 +18436,10 @@ function expressionUsesTracked(expr, ctx) {
     case "Identifier":
       return ctx.trackedVars.has(deSSAVarName(expr.name)) || (ctx.externalTracked?.has(deSSAVarName(expr.name)) ?? false) || (ctx.memoVars?.has(deSSAVarName(expr.name)) ?? false) || (ctx.aliasVars?.has(deSSAVarName(expr.name)) ?? false);
     case "MemberExpression":
+    case "OptionalMemberExpression":
       return expressionUsesTracked(expr.object, ctx);
     case "CallExpression":
+    case "OptionalCallExpression":
       if (expressionUsesTracked(expr.callee, ctx)) return true;
       return expr.arguments.some((arg) => expressionUsesTracked(arg, ctx));
     case "LogicalExpression":
@@ -18618,16 +18661,8 @@ function lowerNodeWithRegionContext(node, t2, ctx, declaredVars, regionCtx) {
       const inNonReactiveScope = !!(ctx.nonReactiveScopeDepth && ctx.nonReactiveScopeDepth > 0);
       const shouldWrapEffect = ctx.wrapTrackedExpressions !== false && !ctx.inRegionMemo && !inNonReactiveScope && expressionUsesTracked(node.test, ctx) && !statementHasEarlyExit(ifStmt, t2);
       if (shouldWrapEffect) {
-        ctx.helpersUsed.add("useEffect");
-        ctx.needsCtx = true;
-        return [
-          t2.expressionStatement(
-            t2.callExpression(t2.identifier(RUNTIME_ALIASES.useEffect), [
-              t2.identifier("__fictCtx"),
-              t2.arrowFunctionExpression([], t2.blockStatement([ifStmt]))
-            ])
-          )
-        ];
+        const effectFn = t2.arrowFunctionExpression([], t2.blockStatement([ifStmt]));
+        return [t2.expressionStatement(buildEffectCall(ctx, t2, effectFn))];
       }
       return [ifStmt];
     }
@@ -18892,16 +18927,8 @@ function lowerStructuredNodeForRegion(node, region, t2, ctx, declaredVars, regio
         ifStmt = buildIfStmt(consequent, alternate);
       }
       if (shouldWrapEffect) {
-        ctx.helpersUsed.add("useEffect");
-        ctx.needsCtx = true;
-        return [
-          t2.expressionStatement(
-            t2.callExpression(t2.identifier(RUNTIME_ALIASES.useEffect), [
-              t2.identifier("__fictCtx"),
-              t2.arrowFunctionExpression([], t2.blockStatement([ifStmt]))
-            ])
-          )
-        ];
+        const effectFn = t2.arrowFunctionExpression([], t2.blockStatement([ifStmt]));
+        return [t2.expressionStatement(buildEffectCall(ctx, t2, effectFn))];
       }
       return [ifStmt];
     }
@@ -19273,30 +19300,16 @@ function wrapInMemo(region, t2, declaredVars, ctx, bodyStatementsOverride, outpu
   const outputNames = outputNamesOverride ?? Array.from(region.declarations).map((name) => deSSAVarName(name));
   const uniqueOutputNames = [...new Set(outputNames)];
   const bindableOutputs = uniqueOutputNames.filter((name) => !declaredVars.has(name));
-  if (debugEnabled("region")) {
-    console.log("Region memo", region.id, {
-      instructions: region.instructions.map((instr) => instr.kind),
-      outputs: uniqueOutputNames
-    });
-  }
+  debugLog("region", `Region memo ${region.id}`, {
+    instructions: region.instructions.map((instr) => instr.kind),
+    outputs: uniqueOutputNames
+  });
   if (uniqueOutputNames.length === 0) {
-    ctx.helpersUsed.add("useEffect");
-    ctx.needsCtx = true;
-    const effectCallArgs = [
-      t2.identifier("__fictCtx"),
-      t2.arrowFunctionExpression([], t2.blockStatement(bodyStatements))
-    ];
-    {
-      const slot = reserveHookSlot(ctx);
-      if (slot >= 0) {
-        effectCallArgs.push(t2.numericLiteral(slot));
-      }
-    }
-    const effectCall = t2.callExpression(t2.identifier(RUNTIME_ALIASES.useEffect), effectCallArgs);
+    const effectFn = t2.arrowFunctionExpression([], t2.blockStatement(bodyStatements));
+    const slot = ctx.inModule ? void 0 : reserveHookSlot(ctx);
+    const effectCall = buildEffectCall(ctx, t2, effectFn, { slot });
     statements.push(t2.expressionStatement(effectCall));
   } else {
-    ctx.helpersUsed.add("useMemo");
-    ctx.needsCtx = true;
     if (!bodyStatementsOverride) {
       const lazyInfo = analyzeHIRConditionalUsage(region, ctx);
       if (lazyInfo) {
@@ -19325,15 +19338,8 @@ function wrapInMemo(region, t2, declaredVars, ctx, bodyStatementsOverride, outpu
     };
     const returnObj = t2.objectExpression(uniqueOutputNames.map((name) => buildOutputProperty(name)));
     const memoBody = t2.blockStatement([...bodyStatements, t2.returnStatement(returnObj)]);
-    const slot = reserveHookSlot(ctx);
-    const memoArgs = [
-      t2.identifier("__fictCtx"),
-      t2.arrowFunctionExpression([], memoBody)
-    ];
-    if (slot >= 0) {
-      memoArgs.push(t2.numericLiteral(slot));
-    }
-    const memoCall = t2.callExpression(t2.identifier(RUNTIME_ALIASES.useMemo), memoArgs);
+    const slot = ctx.inModule ? void 0 : reserveHookSlot(ctx);
+    const memoCall = buildMemoCall(ctx, t2, t2.arrowFunctionExpression([], memoBody), slot);
     const regionVarName = `__region_${region.id}`;
     statements.push(
       t2.variableDeclaration("const", [t2.variableDeclarator(t2.identifier(regionVarName), memoCall)])
@@ -19343,16 +19349,13 @@ function wrapInMemo(region, t2, declaredVars, ctx, bodyStatementsOverride, outpu
       (name) => ctx.trackedVars.has(name) && !isAccessorOutput(name)
     );
     const directOutputs = bindableOutputs.filter((name) => !getterOutputs.includes(name));
-    if (debugEnabled("region")) {
-      console.log("Region debug", {
-        id: region.id,
-        outputs: uniqueOutputNames,
-        getterOutputs,
-        directOutputs,
-        tracked: Array.from(ctx.trackedVars),
-        memoVars: Array.from(ctx.memoVars ?? [])
-      });
-    }
+    debugLog("region", `Region debug ${region.id}`, {
+      outputs: uniqueOutputNames,
+      getterOutputs,
+      directOutputs,
+      tracked: Array.from(ctx.trackedVars),
+      memoVars: Array.from(ctx.memoVars ?? [])
+    });
     if (directOutputs.length > 0) {
       directOutputs.forEach((name) => declaredVars.add(name));
       statements.push(
@@ -19380,21 +19383,15 @@ function wrapInMemo(region, t2, declaredVars, ctx, bodyStatementsOverride, outpu
       ctx.memoVars?.add(name);
     }
     if (region.hasControlFlow && getterOutputs.length > 0) {
-      ctx.helpersUsed.add("useEffect");
-      ctx.needsCtx = true;
       const effectBody = t2.blockStatement(
         getterOutputs.map((name) => t2.expressionStatement(t2.callExpression(t2.identifier(name), [])))
       );
       statements.push(
         t2.expressionStatement(
-          t2.callExpression(t2.identifier(RUNTIME_ALIASES.useEffect), [
-            t2.identifier("__fictCtx"),
-            t2.arrowFunctionExpression([], effectBody),
-            (() => {
-              const slot2 = reserveHookSlot(ctx);
-              return slot2 >= 0 ? t2.numericLiteral(slot2) : t2.identifier("undefined");
-            })()
-          ])
+          buildEffectCall(ctx, t2, t2.arrowFunctionExpression([], effectBody), {
+            slot: ctx.inModule ? void 0 : reserveHookSlot(ctx),
+            forceSlot: true
+          })
         )
       );
     }
@@ -19608,18 +19605,13 @@ function generateLazyConditionalMemo(region, orderedOutputs, bodyStatements, con
       t2.ifStatement(conditionId, t2.blockStatement(trueBlock), t2.blockStatement(falseBlock))
     );
   }
-  ctx.helpersUsed.add("useMemo");
-  ctx.needsCtx = true;
   const regionVarName = `__region_${region.id}`;
-  const slotForMemo = reserveHookSlot(ctx);
-  const memoArgs = [
-    t2.identifier("__fictCtx"),
-    t2.arrowFunctionExpression([], t2.blockStatement(memoBody))
-  ];
-  if (slotForMemo >= 0) {
-    memoArgs.push(t2.numericLiteral(slotForMemo));
-  }
-  const memoCall = t2.callExpression(t2.identifier("__fictUseMemo"), memoArgs);
+  const memoCall = buildMemoCall(
+    ctx,
+    t2,
+    t2.arrowFunctionExpression([], t2.blockStatement(memoBody)),
+    ctx.inModule ? void 0 : reserveHookSlot(ctx)
+  );
   statements.push(
     t2.variableDeclaration("const", [t2.variableDeclarator(t2.identifier(regionVarName), memoCall)])
   );
@@ -19708,20 +19700,9 @@ function instructionToStatement(instr, t2, declaredVars, ctx, _buildMemoCall) {
     const isReactiveObjectCall = instr.value.kind === "CallExpression" && instr.value.callee.kind === "Identifier" && ["mergeProps"].includes(instr.value.callee.name);
     const isMemoReturningCall = isAccessorReturningCall || isReactiveObjectCall;
     const lowerAssignedValue = (forceAssigned = false) => lowerExpressionWithDeSSA(instr.value, ctx, forceAssigned || isFunctionValue);
-    const buildMemoCall = (expr) => {
-      const args = [
-        t2.identifier("__fictCtx"),
-        t2.arrowFunctionExpression([], expr)
-      ];
-      if (inRegionMemo) {
-        const slot = reserveHookSlot(ctx);
-        if (slot >= 0) {
-          args.push(t2.numericLiteral(slot));
-        }
-      }
-      ctx.helpersUsed.add("useMemo");
-      ctx.needsCtx = true;
-      return t2.callExpression(t2.identifier(RUNTIME_ALIASES.useMemo), args);
+    const buildDerivedMemoCall = (expr) => {
+      const slot = !ctx.inModule && inRegionMemo ? reserveHookSlot(ctx) : void 0;
+      return buildMemoCall(ctx, t2, t2.arrowFunctionExpression([], expr), slot);
     };
     if (isShadowDeclaration && declKind) {
       ctx.trackedVars.delete(baseName2);
@@ -19760,7 +19741,7 @@ function instructionToStatement(instr, t2, declaredVars, ctx, _buildMemoCall) {
           return t2.variableDeclaration(normalizedDecl, [
             t2.variableDeclarator(
               t2.identifier(baseName2),
-              isMemoReturningCall ? derivedExpr : buildMemoCall(derivedExpr)
+              isMemoReturningCall ? derivedExpr : buildDerivedMemoCall(derivedExpr)
             )
           ]);
         }
@@ -19787,7 +19768,7 @@ function instructionToStatement(instr, t2, declaredVars, ctx, _buildMemoCall) {
         return t2.variableDeclaration(normalizedDecl, [
           t2.variableDeclarator(
             t2.identifier(baseName2),
-            isMemoReturningCall ? derivedExpr : buildMemoCall(derivedExpr)
+            isMemoReturningCall ? derivedExpr : buildDerivedMemoCall(derivedExpr)
           )
         ]);
       }
@@ -19796,7 +19777,14 @@ function instructionToStatement(instr, t2, declaredVars, ctx, _buildMemoCall) {
       ]);
     }
     if (aliasVars.has(baseName2) && declaredVars.has(baseName2)) {
-      throw new Error(`Alias reassignment is not supported for "${baseName2}"`);
+      throw new Error(
+        `Alias reassignment is not supported for "${baseName2}".
+
+"${baseName2}" was assigned from a reactive value and cannot be reassigned.
+Consider:
+  - Using a new variable name for the new value
+  - Updating the original reactive source instead`
+      );
     }
     if (capturedTracked && isSignal) {
       return t2.expressionStatement(
@@ -19804,7 +19792,14 @@ function instructionToStatement(instr, t2, declaredVars, ctx, _buildMemoCall) {
       );
     }
     if (aliasVars.has(baseName2) && !declaredVars.has(baseName2)) {
-      throw new Error(`Alias reassignment is not supported for "${baseName2}"`);
+      throw new Error(
+        `Alias reassignment is not supported for "${baseName2}".
+
+"${baseName2}" was assigned from a reactive value and cannot be reassigned.
+Consider:
+  - Using a new variable name for the new value
+  - Updating the original reactive source instead`
+      );
     }
     if (dependsOnTracked && !declKind && !isDestructuringTemp && !isTracked && !isSignal && instr.value.kind === "Identifier" && ctx.trackedVars.has(deSSAVarName(instr.value.name))) {
       const derivedExpr = lowerAssignedValue(true);
@@ -19828,13 +19823,20 @@ function instructionToStatement(instr, t2, declaredVars, ctx, _buildMemoCall) {
         t2.assignmentExpression(
           "=",
           t2.identifier(baseName2),
-          isMemoReturningCall ? derivedExpr : buildMemoCall(derivedExpr)
+          isMemoReturningCall ? derivedExpr : buildDerivedMemoCall(derivedExpr)
         )
       );
     }
     if (declaredVars.has(baseName2)) {
       if (aliasVars.has(baseName2)) {
-        throw new Error(`Alias reassignment is not supported for "${baseName2}"`);
+        throw new Error(
+          `Alias reassignment is not supported for "${baseName2}".
+
+"${baseName2}" was assigned from a reactive value and cannot be reassigned.
+Consider:
+  - Using a new variable name for the new value
+  - Updating the original reactive source instead`
+        );
       }
       if (isSignal) {
         return t2.expressionStatement(
@@ -19876,7 +19878,7 @@ function instructionToStatement(instr, t2, declaredVars, ctx, _buildMemoCall) {
         return t2.variableDeclaration("const", [
           t2.variableDeclarator(
             t2.identifier(baseName2),
-            isMemoReturningCall ? derivedExpr : buildMemoCall(derivedExpr)
+            isMemoReturningCall ? derivedExpr : buildDerivedMemoCall(derivedExpr)
           )
         ]);
       }
@@ -19900,7 +19902,7 @@ function instructionToStatement(instr, t2, declaredVars, ctx, _buildMemoCall) {
       return t2.variableDeclaration("const", [
         t2.variableDeclarator(
           t2.identifier(baseName2),
-          isMemoReturningCall ? derivedExpr : buildMemoCall(derivedExpr)
+          isMemoReturningCall ? derivedExpr : buildDerivedMemoCall(derivedExpr)
         )
       ]);
     }
@@ -19920,8 +19922,6 @@ function instructionToStatement(instr, t2, declaredVars, ctx, _buildMemoCall) {
     const inNonReactiveScope = !!(ctx.nonReactiveScopeDepth && ctx.nonReactiveScopeDepth > 0);
     const shouldWrapExpr = ctx.wrapTrackedExpressions !== false && !inNonReactiveScope && (usesTracked || hasTrackedControlDep);
     if (shouldWrapExpr) {
-      ctx.helpersUsed.add("useEffect");
-      ctx.needsCtx = true;
       const depReads = [];
       if (hasTrackedControlDep) {
         const uniqueDeps = new Set(Array.from(controlDeps).map((dep) => deSSAVarName(dep)));
@@ -19933,12 +19933,8 @@ function instructionToStatement(instr, t2, declaredVars, ctx, _buildMemoCall) {
       }
       const loweredExpr = lowerExpressionWithDeSSA(instr.value, ctx);
       const effectBody = depReads.length > 0 ? ctx.t.blockStatement([...depReads, ctx.t.expressionStatement(loweredExpr)]) : loweredExpr;
-      return t2.expressionStatement(
-        t2.callExpression(t2.identifier(RUNTIME_ALIASES.useEffect), [
-          t2.identifier("__fictCtx"),
-          ctx.t.isBlockStatement(effectBody) ? t2.arrowFunctionExpression([], effectBody) : t2.arrowFunctionExpression([], effectBody)
-        ])
-      );
+      const effectFn = ctx.t.isBlockStatement(effectBody) ? t2.arrowFunctionExpression([], effectBody) : t2.arrowFunctionExpression([], effectBody);
+      return t2.expressionStatement(buildEffectCall(ctx, t2, effectFn));
     }
     return t2.expressionStatement(lowerExpressionWithDeSSA(instr.value, ctx));
   }
@@ -20481,6 +20477,7 @@ function createCodegenContext(t2) {
     mutatedVars: /* @__PURE__ */ new Set(),
     inRegionMemo: false,
     inListRender: false,
+    inModule: false,
     nextHookSlot: HOOK_SLOT_BASE,
     nonReactiveScopeDepth: 0,
     inConditional: 0,
@@ -20801,7 +20798,15 @@ function detectDerivedCycles(fn, _scopeResult) {
     if (visiting.has(node)) {
       const idx = stack.indexOf(node);
       const cycle = idx >= 0 ? [...stack.slice(idx), node] : [...stack, node];
-      throw new Error(`Detected cyclic derived dependency: ${cycle.join(" -> ")}`);
+      throw new Error(
+        `Detected cyclic derived dependency: ${cycle.join(" -> ")}
+
+Tip: This usually happens when derived values depend on each other in a loop.
+Consider:
+  - Using untrack() to break the dependency cycle
+  - Restructuring your derived values to avoid circular dependencies
+  - Moving one of the values to $state if it should be independently mutable`
+      );
     }
     if (visited.has(node)) return;
     visiting.add(node);
@@ -20816,12 +20821,11 @@ function detectDerivedCycles(fn, _scopeResult) {
   for (const node of graph.keys()) {
     visit(node);
   }
-  if (debugEnabled("cycles")) {
-    console.error(
-      "cycle graph",
-      Array.from(graph.entries()).map(([k, v]) => [k, Array.from(v)])
-    );
-  }
+  debugLog(
+    "cycles",
+    "cycle graph",
+    Array.from(graph.entries()).map(([k, v]) => [k, Array.from(v)])
+  );
 }
 function collectExpressionIdentifiers(expr, into) {
   if (!expr || typeof expr !== "object") return;
@@ -21917,22 +21921,32 @@ function lowerExpressionImpl(expr, ctx, _isAssigned = false) {
       return t2.identifier("undefined");
     case "CallExpression": {
       if (expr.callee.kind === "Identifier" && expr.callee.name === "$state") {
+        const args = lowerCallArguments(expr.arguments);
+        if (ctx.inModule) {
+          ctx.helpersUsed.add("signal");
+          return t2.callExpression(t2.identifier(RUNTIME_ALIASES.signal), args);
+        }
         ctx.helpersUsed.add("useSignal");
         ctx.needsCtx = true;
         return t2.callExpression(t2.identifier(RUNTIME_ALIASES.useSignal), [
           t2.identifier("__fictCtx"),
-          ...lowerCallArguments(expr.arguments)
+          ...args
         ]);
       }
       if (expr.callee.kind === "Identifier" && expr.callee.name === "$effect") {
+        const args = lowerCallArguments(
+          expr.arguments,
+          (arg) => arg.kind === "ArrowFunction" || arg.kind === "FunctionExpression" ? withNonReactiveScope(ctx, () => lowerExpression(arg, ctx)) : lowerExpression(arg, ctx)
+        );
+        if (ctx.inModule) {
+          ctx.helpersUsed.add("effect");
+          return t2.callExpression(t2.identifier(RUNTIME_ALIASES.effect), args);
+        }
         ctx.helpersUsed.add("useEffect");
         ctx.needsCtx = true;
         return t2.callExpression(t2.identifier(RUNTIME_ALIASES.useEffect), [
           t2.identifier("__fictCtx"),
-          ...lowerCallArguments(
-            expr.arguments,
-            (arg) => arg.kind === "ArrowFunction" || arg.kind === "FunctionExpression" ? withNonReactiveScope(ctx, () => lowerExpression(arg, ctx)) : lowerExpression(arg, ctx)
-          )
+          ...args
         ]);
       }
       if (expr.callee.kind === "Identifier" && expr.callee.name === "__forOf") {
@@ -22824,6 +22838,16 @@ function isExpressionReactive(expr, ctx) {
   for (const dep of deps) {
     if (ctx.trackedVars.has(dep)) return true;
   }
+  if (ctx.memoVars) {
+    for (const dep of deps) {
+      if (ctx.memoVars.has(dep)) return true;
+    }
+  }
+  if (ctx.signalVars) {
+    for (const dep of deps) {
+      if (ctx.signalVars.has(dep)) return true;
+    }
+  }
   for (const region of regionsToCheck) {
     for (const dep of deps) {
       if (region.declarations.has(dep) || region.dependencies.has(dep)) {
@@ -23091,8 +23115,12 @@ function lowerIntrinsicElement(jsx, ctx) {
   const regionMeta = containingRegion ? regionInfoToMetadata(containingRegion) : null;
   const shouldMemo = !ctx.inListRender && !(ctx.inConditional && ctx.inConditional > 0) && regionMeta ? shouldMemoizeRegion(regionMeta) : false;
   if (shouldMemo) {
-    ctx.helpersUsed.add("useMemo");
-    ctx.needsCtx = true;
+    if (ctx.inModule) {
+      ctx.helpersUsed.add("memo");
+    } else {
+      ctx.helpersUsed.add("useMemo");
+      ctx.needsCtx = true;
+    }
   }
   const hoistedTmplId = getOrCreateHoistedTemplate(html, ctx);
   const rootId = genTemp(ctx, "root");
@@ -23366,16 +23394,15 @@ function lowerIntrinsicElement(jsx, ctx) {
   statements.push(t2.returnStatement(elId));
   const body = t2.blockStatement(statements);
   if (shouldMemo && containingRegion) {
-    const memoArgs = [
-      t2.identifier("__fictCtx"),
-      t2.arrowFunctionExpression([], body)
-    ];
+    const memoBody = t2.arrowFunctionExpression([], body);
+    if (ctx.inModule) {
+      return t2.callExpression(t2.callExpression(t2.identifier(RUNTIME_ALIASES.memo), [memoBody]), []);
+    }
+    const memoArgs = [t2.identifier("__fictCtx"), memoBody];
     if (ctx.isComponentFn) {
-      {
-        const slot = reserveHookSlot2(ctx);
-        if (slot >= 0) {
-          memoArgs.push(t2.numericLiteral(slot));
-        }
+      const slot = reserveHookSlot2(ctx);
+      if (slot >= 0) {
+        memoArgs.push(t2.numericLiteral(slot));
       }
     }
     return t2.callExpression(t2.callExpression(t2.identifier(RUNTIME_ALIASES.useMemo), memoArgs), []);
@@ -23435,9 +23462,9 @@ function emitHIRChildBinding(markerId, expr, statements, ctx, containingRegion)
     emitConditionalChild(parentId, markerId, expr, statements, ctx);
     return;
   }
-  if (expr.kind === "CallExpression") {
+  if (expr.kind === "CallExpression" || expr.kind === "OptionalCallExpression") {
     const callee = expr.callee;
-    if (callee.kind === "MemberExpression" && callee.property.kind === "Identifier" && callee.property.name === "map") {
+    if ((callee.kind === "MemberExpression" || callee.kind === "OptionalMemberExpression") && callee.property.kind === "Identifier" && callee.property.name === "map") {
       emitListChild(parentId, markerId, expr, statements, ctx);
       return;
     }
@@ -23477,10 +23504,14 @@ function emitConditionalChild(parentId, markerId, expr, statements, ctx) {
   ctx.helpersUsed.add("conditional");
   ctx.helpersUsed.add("createElement");
   ctx.helpersUsed.add("onDestroy");
-  ctx.helpersUsed.add("toNodeArray");
   let condition;
   let consequent;
   let alternate = null;
+  const lowerBranch = (branch) => {
+    const listExpr = buildListCallExpression(branch, statements, ctx);
+    if (listExpr) return listExpr;
+    return lowerDomExpression(branch, ctx);
+  };
   const enterConditional = () => {
     ctx.inConditional = (ctx.inConditional ?? 0) + 1;
   };
@@ -23490,13 +23521,13 @@ function emitConditionalChild(parentId, markerId, expr, statements, ctx) {
   if (expr.kind === "ConditionalExpression") {
     condition = lowerDomExpression(expr.test, ctx);
     enterConditional();
-    consequent = lowerDomExpression(expr.consequent, ctx);
-    alternate = lowerDomExpression(expr.alternate, ctx);
+    consequent = lowerBranch(expr.consequent);
+    alternate = lowerBranch(expr.alternate);
     exitConditional();
   } else if (expr.kind === "LogicalExpression" && expr.operator === "&&") {
     condition = lowerDomExpression(expr.left, ctx);
     enterConditional();
-    consequent = lowerDomExpression(expr.right, ctx);
+    consequent = lowerBranch(expr.right);
     exitConditional();
   } else {
     return;
@@ -23518,29 +23549,11 @@ function emitConditionalChild(parentId, markerId, expr, statements, ctx) {
       )
     ])
   );
-  const markersId = genTemp(ctx, "markers");
-  statements.push(
-    t2.variableDeclaration("const", [
-      t2.variableDeclarator(
-        markersId,
-        t2.callExpression(t2.identifier(RUNTIME_ALIASES.toNodeArray), [
-          t2.memberExpression(bindingId, t2.identifier("marker"))
-        ])
-      )
-    ])
-  );
-  const mId = genTemp(ctx, "m");
   statements.push(
-    t2.forOfStatement(
-      t2.variableDeclaration("const", [t2.variableDeclarator(mId)]),
-      markersId,
-      t2.blockStatement([
-        t2.expressionStatement(
-          t2.callExpression(t2.memberExpression(parentId, t2.identifier("insertBefore")), [
-            mId,
-            markerId
-          ])
-        )
+    t2.expressionStatement(
+      t2.callExpression(t2.memberExpression(parentId, t2.identifier("insertBefore")), [
+        t2.memberExpression(bindingId, t2.identifier("marker")),
+        markerId
       ])
     )
   );
@@ -23890,10 +23903,18 @@ function applySelectorHoist(callbackExpr, itemParamName, keyParamName, statement
   };
   const visitNode = (node) => {
     if (t2.isFunctionExpression(node) || t2.isArrowFunctionExpression(node)) {
-      if (node !== callbackExpr) return;
+      if (node !== callbackExpr) {
+        if (t2.isBlockStatement(node.body)) {
+          node.body.body.forEach((stmt) => visitNode(stmt));
+        } else if (t2.isExpression(node.body)) {
+          visitNode(node.body);
+        }
+        return;
+      }
     }
-    if (t2.isCallExpression(node) && t2.isIdentifier(node.callee)) {
-      if (node.callee.name === RUNTIME_ALIASES.bindClass) {
+    if (t2.isCallExpression(node)) {
+      const calleeName = t2.isIdentifier(node.callee) ? node.callee.name : t2.isMemberExpression(node.callee) && t2.isIdentifier(node.callee.property) ? node.callee.property.name : null;
+      if (calleeName === RUNTIME_ALIASES.bindClass || calleeName === "bindClass") {
         const handler = node.arguments[1];
         if (handler && (t2.isArrowFunctionExpression(handler) || t2.isFunctionExpression(handler))) {
           rewriteInFunction(handler);
@@ -23976,20 +23997,26 @@ function applySelectorHoist(callbackExpr, itemParamName, keyParamName, statement
     }
   }
 }
-function emitListChild(parentId, markerId, expr, statements, ctx) {
+function buildListCallExpression(expr, statements, ctx) {
   const { t: t2 } = ctx;
-  if (expr.kind !== "CallExpression" || expr.callee.kind !== "MemberExpression") {
-    return;
+  if (expr.kind !== "CallExpression" && expr.kind !== "OptionalCallExpression") {
+    return null;
+  }
+  if (expr.callee.kind !== "MemberExpression" && expr.callee.kind !== "OptionalMemberExpression") {
+    return null;
   }
-  const arrayExpr = lowerDomExpression(expr.callee.object, ctx);
+  if (expr.callee.property.kind !== "Identifier" || expr.callee.property.name !== "map") {
+    return null;
+  }
+  const isOptional = expr.kind === "OptionalCallExpression" || expr.callee.kind === "OptionalMemberExpression" && expr.callee.optional;
+  const arrayExprBase = lowerDomExpression(expr.callee.object, ctx);
+  const arrayExpr = isOptional ? t2.logicalExpression("??", arrayExprBase, t2.arrayExpression([])) : arrayExprBase;
   const mapCallback = expr.arguments[0];
   if (!mapCallback) {
     throw new Error("map callback is required");
   }
   const keyExpr = extractKeyFromMapCallback(mapCallback);
   const isKeyed = !!keyExpr;
-  ctx.helpersUsed.add("onDestroy");
-  ctx.helpersUsed.add("toNodeArray");
   if (isKeyed) {
     ctx.helpersUsed.add("keyedList");
   } else {
@@ -24017,6 +24044,7 @@ function emitListChild(parentId, markerId, expr, statements, ctx) {
   ctx.inListRender = true;
   let callbackExpr = lowerExpression(mapCallback, ctx);
   ctx.inListRender = prevInListRender;
+  const capturedKeyParamName = ctx.listKeyParamName;
   ctx.listKeyExpr = prevListKeyExpr;
   ctx.listItemParamName = prevListItemParamName;
   ctx.listKeyParamName = prevListKeyParamName;
@@ -24054,18 +24082,17 @@ function emitListChild(parentId, markerId, expr, statements, ctx) {
       }
     }
   }
-  const listId = genTemp(ctx, "list");
   if (isKeyed) {
     const itemParamName = t2.isArrowFunctionExpression(callbackExpr) || t2.isFunctionExpression(callbackExpr) ? t2.isIdentifier(callbackExpr.params[0]) ? callbackExpr.params[0].name : null : null;
-    const keyParamName = ctx.listKeyParamName ?? null;
     applySelectorHoist(
       callbackExpr,
       itemParamName,
-      keyParamName,
+      capturedKeyParamName ?? null,
       statements,
       ctx
     );
   }
+  let listCall;
   if (isKeyed && keyExpr) {
     let keyExprAst = lowerExpression(keyExpr, ctx);
     if (t2.isArrowFunctionExpression(callbackExpr) || t2.isFunctionExpression(callbackExpr)) {
@@ -24108,19 +24135,12 @@ function emitListChild(parentId, markerId, expr, statements, ctx) {
       }
     }
     statements.push(...hoistedStatements);
-    statements.push(
-      t2.variableDeclaration("const", [
-        t2.variableDeclarator(
-          listId,
-          t2.callExpression(t2.identifier(RUNTIME_ALIASES.keyedList), [
-            t2.arrowFunctionExpression([], arrayExpr),
-            keyFn,
-            callbackExpr,
-            t2.booleanLiteral(hasIndexParam)
-          ])
-        )
-      ])
-    );
+    listCall = t2.callExpression(t2.identifier(RUNTIME_ALIASES.keyedList), [
+      t2.arrowFunctionExpression([], arrayExpr),
+      keyFn,
+      callbackExpr,
+      t2.booleanLiteral(hasIndexParam)
+    ]);
   } else {
     statements.push(...hoistedStatements);
     const itemParamName = t2.isArrowFunctionExpression(callbackExpr) || t2.isFunctionExpression(callbackExpr) ? t2.isIdentifier(callbackExpr.params[0]) ? callbackExpr.params[0].name : "__item" : "__item";
@@ -24130,20 +24150,23 @@ function emitListChild(parentId, markerId, expr, statements, ctx) {
       [t2.identifier(itemParamName), t2.identifier(indexParamName)],
       t2.identifier(indexParamName)
     );
-    statements.push(
-      t2.variableDeclaration("const", [
-        t2.variableDeclarator(
-          listId,
-          t2.callExpression(t2.identifier(RUNTIME_ALIASES.keyedList), [
-            t2.arrowFunctionExpression([], arrayExpr),
-            keyFn,
-            callbackExpr,
-            t2.booleanLiteral(hasIndexParam)
-          ])
-        )
-      ])
-    );
+    listCall = t2.callExpression(t2.identifier(RUNTIME_ALIASES.keyedList), [
+      t2.arrowFunctionExpression([], arrayExpr),
+      keyFn,
+      callbackExpr,
+      t2.booleanLiteral(hasIndexParam)
+    ]);
   }
+  return listCall;
+}
+function emitListChild(parentId, markerId, expr, statements, ctx) {
+  const { t: t2 } = ctx;
+  const listCall = buildListCallExpression(expr, statements, ctx);
+  if (!listCall) return;
+  ctx.helpersUsed.add("onDestroy");
+  ctx.helpersUsed.add("toNodeArray");
+  const listId = genTemp(ctx, "list");
+  statements.push(t2.variableDeclaration("const", [t2.variableDeclarator(listId, listCall)]));
   const markersId = genTemp(ctx, "markers");
   statements.push(
     t2.variableDeclaration("const", [
@@ -24498,8 +24521,14 @@ function lowerTopLevelStatementBlock(statements, ctx, t2, name = "__module_segme
       ctx.hookReturnInfo.set(fn.name, info);
     }
   }
-  const lowered = generateRegionCode(fn, scopeResult, t2, ctx);
-  return { statements: lowered, aliases: aliasVars };
+  const prevInModule = ctx.inModule;
+  ctx.inModule = true;
+  try {
+    const lowered = generateRegionCode(fn, scopeResult, t2, ctx);
+    return { statements: lowered, aliases: aliasVars };
+  } finally {
+    ctx.inModule = prevInModule;
+  }
 }
 function transformControlFlowReturns(statements, ctx) {
   const { t: t2 } = ctx;
@@ -24600,12 +24629,14 @@ function lowerFunctionWithRegions(fn, ctx) {
   const prevWrapTracked = ctx.wrapTrackedExpressions;
   const prevIsComponent = ctx.isComponentFn;
   const prevHookResultVarMap = ctx.hookResultVarMap;
+  const prevInModule = ctx.inModule;
   const scopedTracked = new Set(ctx.trackedVars);
   const shadowedParams = new Set(fn.params.map((p) => deSSAVarName(p.name)));
   fn.params.forEach((p) => scopedTracked.delete(deSSAVarName(p.name)));
   ctx.trackedVars = scopedTracked;
   const prevNeedsCtx = ctx.needsCtx;
   ctx.needsCtx = false;
+  ctx.inModule = false;
   const prevShadowed = ctx.shadowedNames;
   const functionShadowed = new Set(prevShadowed ?? []);
   shadowedParams.forEach((n) => functionShadowed.add(n));
@@ -24890,9 +24921,9 @@ function lowerFunctionWithRegions(fn, ctx) {
       ctx.hookReturnInfo.set(fn.name, info);
     }
   }
-  if (debugEnabled("region") && fn.name === "Counter") {
-    console.log("Tracked vars for Counter", Array.from(ctx.trackedVars));
-    console.log("Memo vars for Counter", Array.from(ctx.memoVars));
+  if (fn.name === "Counter") {
+    debugLog("region", "Tracked vars for Counter", Array.from(ctx.trackedVars));
+    debugLog("region", "Memo vars for Counter", Array.from(ctx.memoVars));
   }
   hookResultVars.forEach((varName) => {
     const hookName = ctx.hookResultVarMap?.get(varName);
@@ -24922,6 +24953,7 @@ function lowerFunctionWithRegions(fn, ctx) {
     ctx.noMemo = prevNoMemo;
     ctx.wrapTrackedExpressions = prevWrapTracked;
     ctx.hookResultVarMap = prevHookResultVarMap;
+    ctx.inModule = prevInModule;
     return null;
   }
   let statements;
@@ -25010,6 +25042,7 @@ function lowerFunctionWithRegions(fn, ctx) {
   ctx.propsParamName = prevPropsParam;
   ctx.propAccessorDecls = prevPropAccessors;
   ctx.delegatedEventsUsed = prevDelegatedEventsUsed;
+  ctx.inModule = prevInModule;
   return funcDecl;
 }
 function flattenRegions(regions) {
@@ -25653,28 +25686,49 @@ function createHIREntrypointVisitor(t2, options) {
             if (!init) return;
             if (isStateCall(init, t2)) {
               if (!fictImports.has("$state")) {
-                throw varPath.buildCodeFrameError('$state() must be imported from "fict"');
+                throw varPath.buildCodeFrameError(
+                  `$state() must be imported from "fict".
+
+Add this import at the top of your file:
+  import { $state } from 'fict'`
+                );
               }
               if (!t2.isIdentifier(varPath.node.id)) {
                 throw varPath.buildCodeFrameError(
-                  "Destructuring $state is not supported. Use a simple identifier."
+                  `Destructuring $state is not supported.
+
+Instead of:  const { a, b } = $state({ a: 1, b: 2 })
+Use:         let state = $state({ a: 1, b: 2 })
+             const { a, b } = state  // read-only aliases
+
+For deep reactivity, consider using $store from 'fict'.`
                 );
               }
               const ownerComponent = varPath.getFunctionParent();
               if (!ownerComponent || !isComponentOrHookDefinition(ownerComponent)) {
                 throw varPath.buildCodeFrameError(
-                  "$state() must be declared inside a component or hook function body"
+                  `$state() must be declared inside a component or hook function body.
+
+For module-level shared state, use one of these alternatives:
+  \u2022 $store from 'fict' - for deep reactive objects
+  \u2022 createSignal from 'fict/advanced' - for primitives`
                 );
               }
               stateVars.add(varPath.node.id.name);
               if (isInsideLoop(varPath) || isInsideConditional(varPath)) {
                 throw varPath.buildCodeFrameError(
-                  "$state() cannot be declared inside loops or conditionals"
+                  `$state() cannot be declared inside loops or conditionals.
+
+Signals must be created at the top level of components for stable identity.
+Move the $state() declaration before the loop/condition.`
                 );
               }
               if (isInsideNestedFunction(varPath)) {
                 throw varPath.buildCodeFrameError(
-                  "$state() cannot be declared inside nested functions"
+                  `$state() cannot be declared inside nested functions.
+
+Move the $state() declaration to the component's top level,
+or extract the nested logic into a custom hook (useXxx).`
                 );
               }
             } else if (t2.isIdentifier(varPath.node.id)) {
@@ -25716,43 +25770,77 @@ function createHIREntrypointVisitor(t2, options) {
               const isVariableDeclarator = parentPath?.isVariableDeclarator() && parentPath.node.init === callPath.node;
               if (!isVariableDeclarator) {
                 throw callPath.buildCodeFrameError(
-                  "$state() must be assigned directly to a variable (e.g. let count = $state(0)). For object state, consider using $store from fict/plus."
+                  `$state() must be assigned directly to a variable.
+
+Correct usage:
+  let count = $state(0)
+  let user = $state({ name: 'Alice' })
+
+For object state with deep reactivity, consider:
+  import { $store } from 'fict'
+  const user = $store({ name: 'Alice', address: { city: 'NYC' } })`
                 );
               }
               if (!t2.isIdentifier(parentPath.node.id)) {
                 throw callPath.buildCodeFrameError(
-                  "Destructuring $state is not supported. Use a simple identifier."
+                  `Destructuring $state is not supported.
+
+Instead of:  const { a, b } = $state({ a: 1, b: 2 })
+Use:         let state = $state({ a: 1, b: 2 })
+             const { a, b } = state  // read-only aliases`
                 );
               }
               const ownerComponent = callPath.getFunctionParent();
               if (!ownerComponent || !isComponentOrHookDefinition(ownerComponent)) {
                 throw callPath.buildCodeFrameError(
-                  "$state() must be declared inside a component or hook function body"
+                  `$state() must be declared inside a component or hook function body.
+
+For module-level shared state, use one of these alternatives:
+  \u2022 $store from 'fict' - for deep reactive objects
+  \u2022 createSignal from 'fict/advanced' - for primitives`
                 );
               }
               if (isInsideLoop(callPath) || isInsideConditional(callPath)) {
                 throw callPath.buildCodeFrameError(
-                  "$state() cannot be declared inside loops or conditionals"
+                  `$state() cannot be declared inside loops or conditionals.
+
+Move the declaration to the top of your component.
+For dynamic collections, consider using $store with an array/object.`
                 );
               }
               if (isInsideNestedFunction(callPath)) {
                 throw callPath.buildCodeFrameError(
-                  "$state() cannot be declared inside nested functions"
+                  `$state() cannot be declared inside nested functions.
+
+Move the declaration to the component's top level,
+or extract the nested logic into a custom hook (useXxx).`
                 );
               }
             }
             if (isEffectCall(callPath.node, t2)) {
               if (!fictImports.has("$effect")) {
-                throw callPath.buildCodeFrameError('$effect() must be imported from "fict"');
+                throw callPath.buildCodeFrameError(
+                  `$effect() must be imported from "fict".
+
+Add this import at the top of your file:
+  import { $effect } from 'fict'`
+                );
               }
               if (isInsideLoop(callPath) || isInsideConditional(callPath)) {
                 throw callPath.buildCodeFrameError(
-                  "$effect() cannot be called inside loops or conditionals"
+                  `$effect() cannot be called inside loops or conditionals.
+
+Effects must be registered at the top level of components.
+For conditional effects, use a condition inside the effect body instead:
+  $effect(() => { if (condition) { /* ... */ } })`
                 );
               }
               if (isInsideNestedFunction(callPath)) {
                 throw callPath.buildCodeFrameError(
-                  "$effect() cannot be called inside nested functions"
+                  `$effect() cannot be called inside nested functions.
+
+Move the effect to the component's top level,
+or extract the nested logic into a custom hook (useXxx).`
                 );
               }
             }
@@ -25840,9 +25928,7 @@ function createHIREntrypointVisitor(t2, options) {
           });
           return usesState;
         };
-        if (process.env.FICT_DEBUG_ALIAS) {
-          console.log("[fict] alias check state vars", Array.from(stateVars));
-        }
+        debugLog("alias", "state vars", Array.from(stateVars));
         path.traverse({
           Function: {
             enter() {
@@ -25855,9 +25941,7 @@ function createHIREntrypointVisitor(t2, options) {
           VariableDeclarator(varPath) {
             const aliasSet = currentAliasSet();
             if (aliasSet && t2.isIdentifier(varPath.node.id) && rhsUsesState(varPath.get("init"))) {
-              if (process.env.FICT_DEBUG_ALIAS) {
-                console.log("[fict] alias add from decl", varPath.node.id.name);
-              }
+              debugLog("alias", "add from decl", varPath.node.id.name);
               aliasSet.add(varPath.node.id.name);
             }
           },
@@ -25868,16 +25952,12 @@ function createHIREntrypointVisitor(t2, options) {
             const targetName = assignPath.node.left.name;
             const rightPath = assignPath.get("right");
             if (rhsUsesState(rightPath)) {
-              if (process.env.FICT_DEBUG_ALIAS) {
-                console.log("[fict] alias add from assign", targetName);
-              }
+              debugLog("alias", "add from assign", targetName);
               aliasSet.add(targetName);
               return;
             }
             if (aliasSet.has(targetName)) {
-              if (process.env.FICT_DEBUG_ALIAS) {
-                console.log("[fict] alias reassignment detected", targetName);
-              }
+              debugLog("alias", "reassignment detected", targetName);
               throw assignPath.buildCodeFrameError(
                 `Alias reassignment is not supported for "${targetName}"`
               );