web: surface optimizer transforms in the tracer instruction list

Show the tailcall and inline transform annotations inline in the tracer's
instruction list, so the optimizer passes applied to each instruction are
visible as you step through the trace.

Author: gnidan

packages/web/src/theme/ProgramExample/TraceDrawer.css

@@ -270,6 +270,14 @@
   border-left: 3px solid #8250df;
 }
 
+/* Inline boundary banner: same purple tint, dashed edge to echo the
+   virtual-activation badge (no real call occurred). */
+.call-info-inline {
+  background: rgba(130, 80, 223, 0.12);
+  color: var(--ifm-color-content);
+  border-left: 3px dashed #8250df;
+}
+
 .call-stack-tailcall,
 .call-stack-inline {
   margin-left: 4px;
@@ -489,6 +497,35 @@
   color: var(--ifm-color-content);
 }
 
+/* Instructions rewritten by the optimizer (transform contexts): a purple
+   inset accent + tint so the spliced/rewritten region reads as a block in
+   the list. The inset shadow avoids shifting the row layout, and the
+   two-class .opcode-item.active rule still wins for the active row. */
+.opcode-item-inline,
+.opcode-item-tailcall {
+  box-shadow: inset 3px 0 0 rgba(130, 80, 223, 0.7);
+  background: rgba(130, 80, 223, 0.06);
+}
+
+/* Per-instruction transform marker, right-aligned in the row. */
+.opcode-transform-tag {
+  margin-left: auto;
+  padding: 0 5px;
+  border-radius: 8px;
+  font-size: 10px;
+  font-weight: 600;
+  white-space: nowrap;
+  background: rgba(130, 80, 223, 0.15);
+  color: var(--ifm-color-content);
+  border: 1px solid rgba(130, 80, 223, 0.45);
+}
+
+/* Inline markers read as "virtual" (dashed), matching the call-stack badge. */
+.opcode-transform-inline {
+  border-style: dashed;
+  font-style: italic;
+}
+
 /* Instruction object footer - user-resizable, scrolls internally */
 .instruction-object-panel {
   position: relative;

packages/web/src/theme/ProgramExample/TraceDrawer.tsx

@@ -252,6 +252,18 @@ function TraceDrawerContent(): JSX.Element {
     [programsTrace, formatPcToInstruction, currentStep],
   );
 
+  // Compiler transform tags per trace step, so the instruction list can
+  // mark which instructions the optimizer rewrote (e.g. the spliced
+  // instructions of an inlined body) without stepping onto each one.
+  const transformsByStep = useMemo<string[][]>(
+    () =>
+      trace.map((s) => {
+        const fi = formatPcToInstruction.get(s.pc);
+        return fi ? extractTransformFromInstruction(fi) : [];
+      }),
+    [trace, formatPcToInstruction],
+  );
+
   // Resolve argument values for call stack frames
   const argCacheRef = useRef<Map<number, ResolvedArg[]>>(new Map());
 
@@ -721,9 +733,11 @@ function TraceDrawerContent(): JSX.Element {
               {currentCallInfo && (
                 <div
                   className={`call-info-bar ${
-                    currentCallInfo.isTailCall
-                      ? "call-info-tailcall"
-                      : `call-info-${currentCallInfo.kind}`
+                    currentCallInfo.isInline
+                      ? "call-info-inline"
+                      : currentCallInfo.isTailCall
+                        ? "call-info-tailcall"
+                        : `call-info-${currentCallInfo.kind}`
                   }`}
                 >
                   {formatCallBanner(currentCallInfo)}
@@ -737,6 +751,7 @@ function TraceDrawerContent(): JSX.Element {
                     trace={trace}
                     currentStep={currentStep}
                     onStepClick={setCurrentStep}
+                    transformsByStep={transformsByStep}
                   />
                 </div>
 
@@ -848,12 +863,15 @@ interface OpcodeListProps {
   trace: TraceStep[];
   currentStep: number;
   onStepClick: (index: number) => void;
+  /** Compiler transform tags per trace step (same index as `trace`). */
+  transformsByStep: string[][];
 }
 
 function OpcodeList({
   trace,
   currentStep,
   onStepClick,
+  transformsByStep,
 }: OpcodeListProps): JSX.Element {
   // Render the full instruction list; the panel scrolls internally.
   // Keep the active step scrolled into view as the trace advances.
@@ -867,18 +885,47 @@ function OpcodeList({
     <div className="opcode-list">
       {trace.map((step, index) => {
         const isActive = index === currentStep;
+        const transforms = transformsByStep[index] ?? [];
+        const isInline = transforms.includes("inline");
+        const isTailCall = transforms.includes("tailcall");
+        const className = [
+          "opcode-item",
+          isActive ? "active" : "",
+          isInline ? "opcode-item-inline" : "",
+          isTailCall ? "opcode-item-tailcall" : "",
+        ]
+          .filter(Boolean)
+          .join(" ");
         return (
           <div
             key={index}
             ref={isActive ? activeRef : undefined}
-            className={`opcode-item ${isActive ? "active" : ""}`}
+            className={className}
             onClick={() => onStepClick(index)}
           >
             <span className="opcode-index">{index + 1}</span>
             <span className="opcode-pc">
               0x{step.pc.toString(16).padStart(4, "0")}
             </span>
             <code className="opcode-name">{step.opcode}</code>
+            {isInline && (
+              <span
+                className="opcode-transform-tag opcode-transform-inline"
+                title={'transform: ["inline"] — spliced from the inlined body'}
+              >
+                ⧉ inline
+              </span>
+            )}
+            {isTailCall && (
+              <span
+                className="opcode-transform-tag opcode-transform-tailcall"
+                title={
+                  'transform: ["tailcall"] — tail-call optimized back-edge'
+                }
+              >
+                ⮌ tailcall
+              </span>
+            )}
           </div>
         );
       })}
@@ -1065,6 +1112,17 @@ function formatCallBanner(info: CallInfo): string {
   if (info.isTailCall) {
     return `Tail call: ${name} (frame reused)`;
   }
+  if (info.isInline) {
+    // No call actually occurs — the body was spliced in at compile time.
+    switch (info.kind) {
+      case "invoke":
+        return `Inlined ${name}${params} (no call — body spliced in)`;
+      case "return":
+        return `End of inlined ${name}()`;
+      case "revert":
+        return `Reverted in inlined ${name}()`;
+    }
+  }
   switch (info.kind) {
     case "invoke": {
       const prefix = info.callType === "create" ? "Creating" : "Calling";