From 3852c0c619d3ce05968d2f8385250c2534cda69a Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sat, 24 Jan 2026 18:50:55 +0100
Subject: [PATCH 01/33] feat: add struct grammar rules to sfml

---
 src/main/antlr/sfml/SFML.g4 | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/src/main/antlr/sfml/SFML.g4 b/src/main/antlr/sfml/SFML.g4
index 3c2e70f78..a68fa01d9 100644
--- a/src/main/antlr/sfml/SFML.g4
+++ b/src/main/antlr/sfml/SFML.g4
@@ -6,10 +6,28 @@ package ca.teamdman.langs;
     public boolean INCLUDE_UNUSED = false; // we want syntax highlighting to not break on unexpected tokens
 }
 
-program : name? trigger* EOF;
+program : name? structDefinition* letStatement* trigger* EOF;
 
 name: NAME string ;
 
+//
+// STRUCT DEFINITIONS
+//
+
+structDefinition : STRUCT identifier structBody END ;
+structBody : structField* ;
+structField : identifier COLON structFieldValue ;
+structFieldValue : sidequalifier slotqualifier?   // composite: TOP SIDE SLOTS 0
+                 | slotqualifier
+                 | label                          // label must come before resourceIdDisjunction to match strings correctly
+                 | resourceIdDisjunction
+                 | number
+                 ;
+
+letStatement : LET identifier EQ_SYMBOL structInstantiation ;
+structInstantiation : identifier LBRACE structFieldAssignment (COMMA structFieldAssignment)* COMMA? RBRACE ;
+structFieldAssignment : identifier COLON structFieldValue ;
+
 //
 // TRIGGERS
 //
@@ -141,7 +159,9 @@ setOp           : OVERALL
 //
 // IO HELPERS
 //
-labelAccess     : label (COMMA label)* roundrobin? sidequalifier? slotqualifier?;
+labelAccess     : label (COMMA label)* roundrobin? sidequalifier? slotqualifier?     #DirectLabelAccess
+                | identifier USING identifier sidequalifier? slotqualifier?        #StructLabelAccess
+                ;
 roundrobin      : ROUND ROBIN BY (LABEL | BLOCK);
 
 label           : (identifier)  #RawLabel
@@ -150,7 +170,7 @@ label           : (identifier)  #RawLabel
 
 emptyslots      : EMPTY (SLOTS | SLOT) IN ;
 
-identifier : (IDENTIFIER | REDSTONE | GLOBAL | SECOND | SECONDS | TOP | BOTTOM | LEFT | RIGHT | FRONT | BACK) ;
+identifier : (IDENTIFIER | REDSTONE | GLOBAL | SECOND | SECONDS | TOP | BOTTOM | LEFT | RIGHT | FRONT | BACK | INPUT | OUTPUT | LABEL | STRUCT | LET | USING | SLOT | SLOTS | SIDE | BLOCK) ;
 
 // GENERAL
 string: STRING ;
@@ -252,6 +272,13 @@ DO              : D O ;
 END             : E N D ;
 NAME            : N A M E ;
 
+// STRUCT SYMBOLS
+STRUCT          : S T R U C T ;
+LET             : L E T ;
+USING           : U S I N G ;
+LBRACE          : '{' ;
+RBRACE          : '}' ;
+
 // GENERAL SYMBOLS
 // used by triggers and as a set operator
 EVERY           : E V E R Y ;

From 1aa745ed75bfc1c99f4daea8a398359108711b91 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sat, 24 Jan 2026 18:51:02 +0100
Subject: [PATCH 02/33] feat: add struct ast classes

---
 .../sfml/ast/CompositeFieldValue.java         | 27 ++++++++++
 .../ca/teamdman/sfml/ast/LetStatement.java    | 15 ++++++
 .../ca/teamdman/sfml/ast/StructAccess.java    | 18 +++++++
 .../teamdman/sfml/ast/StructDefinition.java   | 39 ++++++++++++++
 .../ca/teamdman/sfml/ast/StructField.java     | 15 ++++++
 .../teamdman/sfml/ast/StructFieldValue.java   |  9 ++++
 .../ca/teamdman/sfml/ast/StructInstance.java  | 53 +++++++++++++++++++
 7 files changed, 176 insertions(+)
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/CompositeFieldValue.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/LetStatement.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/StructAccess.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/StructDefinition.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/StructField.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/StructFieldValue.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/StructInstance.java

diff --git a/src/main/java/ca/teamdman/sfml/ast/CompositeFieldValue.java b/src/main/java/ca/teamdman/sfml/ast/CompositeFieldValue.java
new file mode 100644
index 000000000..f06e428c0
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/CompositeFieldValue.java
@@ -0,0 +1,27 @@
+package ca.teamdman.sfml.ast;
+
+/**
+ * Represents a composite struct field value that combines side and slot qualifiers.
+ * Example: TOP SIDE SLOTS 0
+ */
+public record CompositeFieldValue(
+        SideQualifier sides,
+        NumberRangeSet slots
+) implements StructFieldValue {
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder();
+        if (!sides.equals(SideQualifier.NULL)) {
+            sb.append(sides.sides().stream()
+                    .map(Side::toString)
+                    .reduce((a, b) -> a + ", " + b)
+                    .orElse(""));
+            sb.append(" SIDE");
+        }
+        if (!slots.equals(NumberRangeSet.MAX_RANGE)) {
+            if (!sb.isEmpty()) sb.append(" ");
+            sb.append("SLOTS ").append(slots);
+        }
+        return sb.toString();
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/LetStatement.java b/src/main/java/ca/teamdman/sfml/ast/LetStatement.java
new file mode 100644
index 000000000..9d2eb38bb
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/LetStatement.java
@@ -0,0 +1,15 @@
+package ca.teamdman.sfml.ast;
+
+/**
+ * Represents a let statement that binds a struct instance to a variable name.
+ * Example: let smelter = Furnace { label: "my furnaces" }
+ */
+public record LetStatement(
+        String variableName,
+        StructInstance instance
+) implements ASTNode {
+    @Override
+    public String toString() {
+        return "let " + variableName + " = " + instance;
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/StructAccess.java b/src/main/java/ca/teamdman/sfml/ast/StructAccess.java
new file mode 100644
index 000000000..ef01a9c45
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/StructAccess.java
@@ -0,0 +1,18 @@
+package ca.teamdman.sfml.ast;
+
+/**
+ * Represents access to a struct field using the USING keyword.
+ * Example: smelter using input
+ *
+ * This is used to track the original source of a struct field access
+ * before it is resolved into a concrete LabelAccess.
+ */
+public record StructAccess(
+        String variableName,
+        String fieldName
+) implements ASTNode {
+    @Override
+    public String toString() {
+        return variableName + " using " + fieldName;
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/StructDefinition.java b/src/main/java/ca/teamdman/sfml/ast/StructDefinition.java
new file mode 100644
index 000000000..628c507b2
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/StructDefinition.java
@@ -0,0 +1,39 @@
+package ca.teamdman.sfml.ast;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * Represents a struct definition in the program.
+ * Example:
+ * struct Furnace
+ *     input: TOP SIDE SLOTS 0
+ *     fuel: BOTTOM SIDE SLOTS 1
+ *     output: BOTTOM SIDE SLOTS 2
+ * end
+ */
+public record StructDefinition(
+        String name,
+        List<StructField> fields
+) implements ASTNode {
+
+    /**
+     * Gets a field by name from this struct definition.
+     */
+    public Optional<StructField> getField(String fieldName) {
+        return fields.stream()
+                .filter(f -> f.name().equals(fieldName))
+                .findFirst();
+    }
+
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder();
+        sb.append("struct ").append(name).append("\n");
+        for (StructField field : fields) {
+            sb.append("    ").append(field).append("\n");
+        }
+        sb.append("end");
+        return sb.toString();
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/StructField.java b/src/main/java/ca/teamdman/sfml/ast/StructField.java
new file mode 100644
index 000000000..8bc0a6579
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/StructField.java
@@ -0,0 +1,15 @@
+package ca.teamdman.sfml.ast;
+
+/**
+ * Represents a field within a struct definition.
+ * Example: input: TOP SIDE SLOTS 0
+ */
+public record StructField(
+        String name,
+        StructFieldValue value
+) implements ASTNode {
+    @Override
+    public String toString() {
+        return name + ": " + value;
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/StructFieldValue.java b/src/main/java/ca/teamdman/sfml/ast/StructFieldValue.java
new file mode 100644
index 000000000..d3987b323
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/StructFieldValue.java
@@ -0,0 +1,9 @@
+package ca.teamdman.sfml.ast;
+
+/**
+ * Marker interface for values that can appear in struct field definitions.
+ * Used for type safety in struct field value assignments.
+ */
+public sealed interface StructFieldValue extends ASTNode
+        permits SideQualifier, NumberRangeSet, ResourceIdSet, Label, Number, CompositeFieldValue {
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/StructInstance.java b/src/main/java/ca/teamdman/sfml/ast/StructInstance.java
new file mode 100644
index 000000000..55b743086
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/StructInstance.java
@@ -0,0 +1,53 @@
+package ca.teamdman.sfml.ast;
+
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * Represents an instantiation of a struct with overrides.
+ * Example: Furnace { label: "my furnaces" }
+ */
+public record StructInstance(
+        String variableName,
+        StructDefinition definition,
+        Map<String, StructFieldValue> overrides
+) implements ASTNode {
+
+    /**
+     * Resolves a field value, checking overrides first, then the definition.
+     */
+    public Optional<StructFieldValue> resolveField(String fieldName) {
+        // Check overrides first
+        if (overrides.containsKey(fieldName)) {
+            return Optional.of(overrides.get(fieldName));
+        }
+        // Fall back to definition
+        return definition.getField(fieldName).map(StructField::value);
+    }
+
+    /**
+     * Gets the label for this struct instance.
+     * The label must be provided as an override since it binds to actual blocks.
+     */
+    public Optional<Label> getLabel() {
+        StructFieldValue labelValue = overrides.get("label");
+        if (labelValue instanceof Label label) {
+            return Optional.of(label);
+        }
+        return Optional.empty();
+    }
+
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder();
+        sb.append(definition.name()).append(" { ");
+        boolean first = true;
+        for (Map.Entry<String, StructFieldValue> entry : overrides.entrySet()) {
+            if (!first) sb.append(", ");
+            sb.append(entry.getKey()).append(": ").append(entry.getValue());
+            first = false;
+        }
+        sb.append(" }");
+        return sb.toString();
+    }
+}

From c5ea66513da73375301ff23d1580ebc7febf2193 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sat, 24 Jan 2026 18:51:07 +0100
Subject: [PATCH 03/33] refactor: implement structfieldvalue on existing ast
 classes

---
 src/main/java/ca/teamdman/sfml/ast/Label.java          | 2 +-
 src/main/java/ca/teamdman/sfml/ast/Number.java         | 2 +-
 src/main/java/ca/teamdman/sfml/ast/NumberRangeSet.java | 2 +-
 src/main/java/ca/teamdman/sfml/ast/ResourceIdSet.java  | 2 +-
 src/main/java/ca/teamdman/sfml/ast/SideQualifier.java  | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfml/ast/Label.java b/src/main/java/ca/teamdman/sfml/ast/Label.java
index c00b793e2..e5c4f89bd 100644
--- a/src/main/java/ca/teamdman/sfml/ast/Label.java
+++ b/src/main/java/ca/teamdman/sfml/ast/Label.java
@@ -1,6 +1,6 @@
 package ca.teamdman.sfml.ast;
 
-public record Label(String name) implements ASTNode {
+public record Label(String name) implements StructFieldValue {
     @Override
     public String toString() {
         return name;
diff --git a/src/main/java/ca/teamdman/sfml/ast/Number.java b/src/main/java/ca/teamdman/sfml/ast/Number.java
index beda2faa0..aff29d15c 100644
--- a/src/main/java/ca/teamdman/sfml/ast/Number.java
+++ b/src/main/java/ca/teamdman/sfml/ast/Number.java
@@ -1,6 +1,6 @@
 package ca.teamdman.sfml.ast;
 
-public record Number(long value) implements ASTNode {
+public record Number(long value) implements StructFieldValue {
     @Override
     public String toString() {
         return String.valueOf(value);
diff --git a/src/main/java/ca/teamdman/sfml/ast/NumberRangeSet.java b/src/main/java/ca/teamdman/sfml/ast/NumberRangeSet.java
index 7d4c212dd..875ba5c07 100644
--- a/src/main/java/ca/teamdman/sfml/ast/NumberRangeSet.java
+++ b/src/main/java/ca/teamdman/sfml/ast/NumberRangeSet.java
@@ -3,7 +3,7 @@
 import java.util.Arrays;
 import java.util.stream.Collectors;
 
-public record NumberRangeSet(NumberRange[] ranges) implements ASTNode {
+public record NumberRangeSet(NumberRange[] ranges) implements StructFieldValue {
     public static final NumberRangeSet MAX_RANGE = new NumberRangeSet(new NumberRange[]{NumberRange.MAX_RANGE});
     public boolean contains(int value) {
         for (NumberRange range : ranges) {
diff --git a/src/main/java/ca/teamdman/sfml/ast/ResourceIdSet.java b/src/main/java/ca/teamdman/sfml/ast/ResourceIdSet.java
index e2cd19eba..4cb7cdb2b 100644
--- a/src/main/java/ca/teamdman/sfml/ast/ResourceIdSet.java
+++ b/src/main/java/ca/teamdman/sfml/ast/ResourceIdSet.java
@@ -14,7 +14,7 @@
  * A read-only set of {@link ResourceIdentifier} objects.
  * Do NOT modify this after creation since the {@link this#referencedResourceTypes} will become inaccurate.
  */
-public final class ResourceIdSet implements ASTNode {
+public final class ResourceIdSet implements StructFieldValue {
     public static final ResourceIdSet EMPTY = new ResourceIdSet(List.of());
     public static final ResourceIdSet MATCH_ALL = new ResourceIdSet(List.of(ResourceIdentifier.MATCH_ALL));
     private final ResourceIdentifier<?, ?, ?>[] resourceIds;
diff --git a/src/main/java/ca/teamdman/sfml/ast/SideQualifier.java b/src/main/java/ca/teamdman/sfml/ast/SideQualifier.java
index 0a396b99b..785600286 100644
--- a/src/main/java/ca/teamdman/sfml/ast/SideQualifier.java
+++ b/src/main/java/ca/teamdman/sfml/ast/SideQualifier.java
@@ -8,7 +8,7 @@
 import java.util.List;
 import java.util.Objects;
 
-public record SideQualifier(List<Side> sides) implements ASTNode {
+public record SideQualifier(List<Side> sides) implements StructFieldValue {
     public static final SideQualifier NULL = new SideQualifier(List.of(Side.NULL));
 
     public static final SideQualifier ALL = new SideQualifier(List.of(

From 48314d38193cdf539f9ad07a9105c2df2b1c398f Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sat, 24 Jan 2026 18:51:12 +0100
Subject: [PATCH 04/33] feat: add struct support to program and labelaccess

---
 .../ca/teamdman/sfml/ast/LabelAccess.java     | 37 +++++++++++++++++--
 .../java/ca/teamdman/sfml/ast/Program.java    | 30 +++++++++++++++
 2 files changed, 63 insertions(+), 4 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfml/ast/LabelAccess.java b/src/main/java/ca/teamdman/sfml/ast/LabelAccess.java
index c4632233d..2cefd0b11 100644
--- a/src/main/java/ca/teamdman/sfml/ast/LabelAccess.java
+++ b/src/main/java/ca/teamdman/sfml/ast/LabelAccess.java
@@ -3,6 +3,7 @@
 import ca.teamdman.sfm.common.label.LabelPositionHolder;
 import com.mojang.datafixers.util.Pair;
 import net.minecraft.core.BlockPos;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -13,15 +14,43 @@ public record LabelAccess(
         List<Label> labels,
         SideQualifier sides,
         NumberRangeSet slots,
-        RoundRobin roundRobin
+        RoundRobin roundRobin,
+        @Nullable StructAccess structAccess
 ) implements ASTNode {
+
+    /**
+     * Convenience constructor for direct label access (no struct).
+     */
+    public LabelAccess(
+            List<Label> labels,
+            SideQualifier sides,
+            NumberRangeSet slots,
+            RoundRobin roundRobin
+    ) {
+        this(labels, sides, slots, roundRobin, null);
+    }
+
+    /**
+     * Returns true if this label access came from a struct USING clause.
+     */
+    public boolean isStructAccess() {
+        return structAccess != null;
+    }
+
     @Override
     public String toString() {
         StringBuilder builder = new StringBuilder();
-        builder.append(labels.stream().map(Objects::toString).collect(Collectors.joining(", ")));
-        if (roundRobin.isEnabled()) {
-            builder.append(" ").append(roundRobin);
+
+        // If this is a struct access, show the original form
+        if (structAccess != null) {
+            builder.append(structAccess);
+        } else {
+            builder.append(labels.stream().map(Objects::toString).collect(Collectors.joining(", ")));
+            if (roundRobin.isEnabled()) {
+                builder.append(" ").append(roundRobin);
+            }
         }
+
         if (!sides.equals(SideQualifier.NULL)) {
             builder.append(" ");
             builder
diff --git a/src/main/java/ca/teamdman/sfml/ast/Program.java b/src/main/java/ca/teamdman/sfml/ast/Program.java
index 0166e008b..127dd09fd 100644
--- a/src/main/java/ca/teamdman/sfml/ast/Program.java
+++ b/src/main/java/ca/teamdman/sfml/ast/Program.java
@@ -21,6 +21,7 @@
 import java.util.ArrayDeque;
 import java.util.Deque;
 import java.util.List;
+import java.util.Optional;
 import java.util.Set;
 import java.util.function.Consumer;
 
@@ -33,6 +34,10 @@ public record Program(
 
         String name,
 
+        List<StructDefinition> structDefinitions,
+
+        List<LetStatement> letStatements,
+
         List<Trigger> triggers,
 
         Set<String> referencedLabels,
@@ -167,11 +172,36 @@ public int getConditionIndex(IfStatement ifStatement) {
         return -1;
     }
 
+    /**
+     * Gets a struct definition by name.
+     */
+    public Optional<StructDefinition> getStructDefinition(String name) {
+        return structDefinitions.stream()
+                .filter(s -> s.name().equals(name))
+                .findFirst();
+    }
+
+    /**
+     * Gets a struct instance by variable name.
+     */
+    public Optional<StructInstance> getStructInstance(String variableName) {
+        return letStatements.stream()
+                .filter(let -> let.variableName().equals(variableName))
+                .map(LetStatement::instance)
+                .findFirst();
+    }
+
     @Override
     public String toString() {
 
         var rtn = new StringBuilder();
         rtn.append("NAME \"").append(name).append("\"\n");
+        for (StructDefinition structDef : structDefinitions) {
+            rtn.append(structDef).append("\n");
+        }
+        for (LetStatement letStmt : letStatements) {
+            rtn.append(letStmt).append("\n");
+        }
         for (Trigger trigger : triggers) {
             rtn.append(trigger).append("\n");
         }

From 586d8eb68c4e2f5852d82ce0abd2ce0c78799e83 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sat, 24 Jan 2026 18:51:17 +0100
Subject: [PATCH 05/33] feat: add struct visitor methods to astbuilder

---
 .../java/ca/teamdman/sfml/ast/ASTBuilder.java | 241 +++++++++++++++++-
 1 file changed, 238 insertions(+), 3 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java b/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
index 7d0c4d10f..add868252 100644
--- a/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
+++ b/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
@@ -11,6 +11,7 @@
 
 import java.lang.ref.WeakReference;
 import java.util.*;
+import java.util.AbstractMap.SimpleEntry;
 import java.util.stream.Collectors;
 
 public class ASTBuilder extends SFMLBaseVisitor<ASTNode> {
@@ -23,6 +24,12 @@ public class ASTBuilder extends SFMLBaseVisitor<ASTNode> {
     /// Used for program editor context actions; ctrl+space on a token
     private final List<Pair<WeakReference<ASTNode>, ParserRuleContext>> AST_NODE_CONTEXTS = new LinkedList<>();
 
+    /// Struct definitions indexed by name, populated during AST building
+    private final Map<String, StructDefinition> STRUCT_DEFINITIONS = new HashMap<>();
+
+    /// Struct instances indexed by variable name, populated during AST building
+    private final Map<String, StructInstance> STRUCT_INSTANCES = new HashMap<>();
+
     /// @return hierarchy of nodes; e.g., Program > Trigger > Block > IOStatement > LabelAccess > Label
     public List<Pair<ASTNode, ParserRuleContext>> getNodesUnderCursor(int cursorPos) {
 
@@ -174,21 +181,184 @@ public Program visitProgram(SFMLParser.ProgramContext ctx) {
             throw new AssertionError("Program execution is disabled via config");
         }
         var name = visitName(ctx.name());
+
+        // Process struct definitions first
+        var structDefinitions = ctx
+                .structDefinition()
+                .stream()
+                .map(this::visitStructDefinition)
+                .collect(Collectors.toList());
+
+        // Process let statements next (they reference struct definitions)
+        var letStatements = ctx
+                .letStatement()
+                .stream()
+                .map(this::visitLetStatement)
+                .collect(Collectors.toList());
+
+        // Process triggers last (they can reference struct instances)
         var triggers = ctx
                 .trigger()
                 .stream()
                 .map(this::visit)
                 .map(Trigger.class::cast)
                 .collect(Collectors.toList());
+
         var labels = USED_LABELS
                 .stream()
                 .map(Label::name)
                 .collect(Collectors.toSet());
-        Program program = new Program(this, name.value(), triggers, labels, USED_RESOURCES);
+        Program program = new Program(this, name.value(), structDefinitions, letStatements, triggers, labels, USED_RESOURCES);
         trackNode(program, ctx);
         return program;
     }
 
+    // ===== STRUCT DEFINITIONS =====
+
+    public StructDefinition visitStructDefinition(SFMLParser.StructDefinitionContext ctx) {
+        String name = ctx.identifier().getText();
+
+        // Check for duplicate struct names
+        if (STRUCT_DEFINITIONS.containsKey(name)) {
+            throw new IllegalArgumentException("Duplicate struct definition: " + name);
+        }
+
+        List<StructField> fields = new ArrayList<>();
+        Set<String> fieldNames = new HashSet<>();
+
+        for (SFMLParser.StructFieldContext fieldCtx : ctx.structBody().structField()) {
+            StructField field = visitStructField(fieldCtx);
+
+            // Check for duplicate field names
+            if (!fieldNames.add(field.name())) {
+                throw new IllegalArgumentException(
+                        "Duplicate field name '" + field.name() + "' in struct " + name
+                );
+            }
+
+            fields.add(field);
+        }
+
+        StructDefinition structDef = new StructDefinition(name, fields);
+        STRUCT_DEFINITIONS.put(name, structDef);
+        trackNode(structDef, ctx);
+        return structDef;
+    }
+
+    public StructField visitStructField(SFMLParser.StructFieldContext ctx) {
+        String fieldName = ctx.identifier().getText();
+        StructFieldValue value = visitStructFieldValue(ctx.structFieldValue());
+        StructField field = new StructField(fieldName, value);
+        trackNode(field, ctx);
+        return field;
+    }
+
+    public StructFieldValue visitStructFieldValue(SFMLParser.StructFieldValueContext ctx) {
+        // composite: sidequalifier slotqualifier?
+        if (ctx.sidequalifier() != null) {
+            SideQualifier sides = (SideQualifier) visit(ctx.sidequalifier());
+            NumberRangeSet slots = visitSlotqualifier(ctx.slotqualifier());
+            if (!slots.equals(NumberRangeSet.MAX_RANGE)) {
+                // Has both sides and slots - composite value
+                CompositeFieldValue composite = new CompositeFieldValue(sides, slots);
+                trackNode(composite, ctx);
+                return composite;
+            }
+            // Just sides
+            return sides;
+        }
+
+        // slotqualifier only
+        if (ctx.slotqualifier() != null) {
+            return visitSlotqualifier(ctx.slotqualifier());
+        }
+
+        // resourceIdDisjunction
+        if (ctx.resourceIdDisjunction() != null) {
+            return visitResourceIdDisjunction(ctx.resourceIdDisjunction());
+        }
+
+        // label
+        if (ctx.label() != null) {
+            return (Label) visit(ctx.label());
+        }
+
+        // number
+        if (ctx.number() != null) {
+            return visitNumber(ctx.number());
+        }
+
+        throw new IllegalStateException("Unknown struct field value type");
+    }
+
+    public LetStatement visitLetStatement(SFMLParser.LetStatementContext ctx) {
+        String variableName = ctx.identifier().getText();
+
+        // Check for duplicate variable names
+        if (STRUCT_INSTANCES.containsKey(variableName)) {
+            throw new IllegalArgumentException("Duplicate variable name: " + variableName);
+        }
+
+        StructInstance instance = visitStructInstantiation(ctx.structInstantiation(), variableName);
+        LetStatement letStatement = new LetStatement(variableName, instance);
+
+        STRUCT_INSTANCES.put(variableName, instance);
+        trackNode(letStatement, ctx);
+        return letStatement;
+    }
+
+    public StructInstance visitStructInstantiation(SFMLParser.StructInstantiationContext ctx, String variableName) {
+        String structName = ctx.identifier().getText();
+
+        // Look up the struct definition
+        StructDefinition definition = STRUCT_DEFINITIONS.get(structName);
+        if (definition == null) {
+            throw new IllegalArgumentException("Unknown struct: " + structName);
+        }
+
+        // Process field assignments
+        Map<String, StructFieldValue> overrides = new LinkedHashMap<>();
+        for (SFMLParser.StructFieldAssignmentContext assignCtx : ctx.structFieldAssignment()) {
+            Map.Entry<String, StructFieldValue> entry = parseStructFieldAssignment(assignCtx);
+
+            // Check that the field exists in the struct definition
+            // "label" is a special required field that doesn't need to be defined in the struct
+            if (!entry.getKey().equals("label") && definition.getField(entry.getKey()).isEmpty()) {
+                throw new IllegalArgumentException(
+                        "Unknown field '" + entry.getKey() + "' in struct " + structName
+                );
+            }
+
+            // Check for duplicate assignments
+            if (overrides.containsKey(entry.getKey())) {
+                throw new IllegalArgumentException(
+                        "Duplicate field assignment '" + entry.getKey() + "' in struct instantiation"
+                );
+            }
+
+            overrides.put(entry.getKey(), entry.getValue());
+        }
+
+        // Validate that label override is present
+        if (!overrides.containsKey("label")) {
+            throw new IllegalArgumentException(
+                    "Struct instantiation must include a 'label' override to bind to actual blocks"
+            );
+        }
+
+        StructInstance instance = new StructInstance(variableName, definition, overrides);
+        trackNode(instance, ctx);
+        return instance;
+    }
+
+    private Map.Entry<String, StructFieldValue> parseStructFieldAssignment(SFMLParser.StructFieldAssignmentContext ctx) {
+        String fieldName = ctx.identifier().getText();
+        StructFieldValue value = visitStructFieldValue(ctx.structFieldValue());
+        return new SimpleEntry<>(fieldName, value);
+    }
+
+    // ===== END STRUCT DEFINITIONS =====
+
     @Override
     public ASTNode visitTimerTrigger(SFMLParser.TimerTriggerContext ctx) {
         // create timer trigger
@@ -333,9 +503,13 @@ public OutputStatement visitOutputStatement(SFMLParser.OutputStatementContext ct
         return outputStatement;
     }
 
-    @Override
     public LabelAccess visitLabelAccess(SFMLParser.LabelAccessContext ctx) {
+        // Delegate to the appropriate alternative visitor
+        return (LabelAccess) visit(ctx);
+    }
 
+    @Override
+    public LabelAccess visitDirectLabelAccess(SFMLParser.DirectLabelAccessContext ctx) {
         var directionQualifierCtx = ctx.sidequalifier();
         SideQualifier sideQualifier;
         if (directionQualifierCtx == null) {
@@ -347,7 +521,68 @@ public LabelAccess visitLabelAccess(SFMLParser.LabelAccessContext ctx) {
                 ctx.label().stream().map(this::visit).map(Label.class::cast).collect(Collectors.toList()),
                 sideQualifier,
                 visitSlotqualifier(ctx.slotqualifier()),
-                visitRoundrobin(ctx.roundrobin())
+                visitRoundrobin(ctx.roundrobin()),
+                null // No struct access for direct label access
+        );
+        trackNode(labelAccess, ctx);
+        return labelAccess;
+    }
+
+    @Override
+    public LabelAccess visitStructLabelAccess(SFMLParser.StructLabelAccessContext ctx) {
+        String variableName = ctx.identifier(0).getText();
+        String fieldName = ctx.identifier(1).getText();
+
+        // Validate that the variable exists
+        StructInstance instance = STRUCT_INSTANCES.get(variableName);
+        if (instance == null) {
+            throw new IllegalArgumentException("Unknown struct variable: " + variableName);
+        }
+
+        // Validate that the field exists
+        Optional<StructFieldValue> fieldValue = instance.resolveField(fieldName);
+        if (fieldValue.isEmpty()) {
+            throw new IllegalArgumentException(
+                    "Unknown field '" + fieldName + "' in struct variable " + variableName
+            );
+        }
+
+        // Get the label from the struct instance
+        Label label = instance.getLabel().orElseThrow(() ->
+                new IllegalStateException("Struct instance " + variableName + " has no label")
+        );
+
+        // Resolve sides and slots from the field value
+        SideQualifier sides = SideQualifier.NULL;
+        NumberRangeSet slots = NumberRangeSet.MAX_RANGE;
+
+        StructFieldValue resolvedField = fieldValue.get();
+        if (resolvedField instanceof CompositeFieldValue composite) {
+            sides = composite.sides();
+            slots = composite.slots();
+        } else if (resolvedField instanceof SideQualifier sq) {
+            sides = sq;
+        } else if (resolvedField instanceof NumberRangeSet nrs) {
+            slots = nrs;
+        }
+
+        // Allow explicit side/slot overrides in the USING clause
+        if (ctx.sidequalifier() != null) {
+            sides = (SideQualifier) visit(ctx.sidequalifier());
+        }
+        if (ctx.slotqualifier() != null) {
+            slots = visitSlotqualifier(ctx.slotqualifier());
+        }
+
+        StructAccess structAccess = new StructAccess(variableName, fieldName);
+        trackNode(structAccess, ctx);
+
+        LabelAccess labelAccess = new LabelAccess(
+                List.of(label),
+                sides,
+                slots,
+                RoundRobin.disabled(),
+                structAccess
         );
         trackNode(labelAccess, ctx);
         return labelAccess;

From 163536669e59b34e2cb1610990cf6eba77a3db5c Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sat, 24 Jan 2026 18:51:22 +0100
Subject: [PATCH 06/33] feat: add struct linters

---
 .../common/localization/LocalizationKeys.java |  8 ++
 .../linting/StructDefinitionLinter.java       | 55 +++++++++++
 .../program/linting/StructUsageLinter.java    | 92 +++++++++++++++++++
 .../common/registry/SFMProgramLinters.java    | 12 +++
 4 files changed, 167 insertions(+)
 create mode 100644 src/main/java/ca/teamdman/sfm/common/program/linting/StructDefinitionLinter.java
 create mode 100644 src/main/java/ca/teamdman/sfm/common/program/linting/StructUsageLinter.java

diff --git a/src/main/java/ca/teamdman/sfm/common/localization/LocalizationKeys.java b/src/main/java/ca/teamdman/sfm/common/localization/LocalizationKeys.java
index bc12902c3..386ff73e8 100644
--- a/src/main/java/ca/teamdman/sfm/common/localization/LocalizationKeys.java
+++ b/src/main/java/ca/teamdman/sfm/common/localization/LocalizationKeys.java
@@ -476,6 +476,14 @@ public final class LocalizationKeys {
             "program.sfm.warnings.round_robin_smelly_count",
             "Round robin by label should be used with more than one label, statement %s"
     );
+    public static final LocalizationEntry PROGRAM_WARNING_UNUSED_STRUCT = new LocalizationEntry(
+            "program.sfm.warnings.unused_struct",
+            "Struct \"%s\" is defined but never instantiated."
+    );
+    public static final LocalizationEntry PROGRAM_WARNING_UNUSED_STRUCT_INSTANCE = new LocalizationEntry(
+            "program.sfm.warnings.unused_struct_instance",
+            "Struct instance \"%s\" is defined but never used in a USING clause."
+    );
     public static final LocalizationEntry PROGRAM_ERROR_COMPILE_FAILED = new LocalizationEntry(
             "program.sfm.error.compile_failed",
             "Failed to compile."
diff --git a/src/main/java/ca/teamdman/sfm/common/program/linting/StructDefinitionLinter.java b/src/main/java/ca/teamdman/sfm/common/program/linting/StructDefinitionLinter.java
new file mode 100644
index 000000000..4a54db946
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfm/common/program/linting/StructDefinitionLinter.java
@@ -0,0 +1,55 @@
+package ca.teamdman.sfm.common.program.linting;
+
+import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
+import ca.teamdman.sfm.common.label.LabelPositionHolder;
+import ca.teamdman.sfml.ast.LetStatement;
+import ca.teamdman.sfml.ast.Program;
+import ca.teamdman.sfml.ast.StructDefinition;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.Level;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import static ca.teamdman.sfm.common.localization.LocalizationKeys.PROGRAM_WARNING_UNUSED_STRUCT;
+
+/**
+ * Linter that validates struct definitions are actually used.
+ */
+public class StructDefinitionLinter implements IProgramLinter {
+    @Override
+    public void gatherWarnings(
+            Program program,
+            LabelPositionHolder labelPositionHolder,
+            @Nullable ManagerBlockEntity managerBlockEntity,
+            ProblemTracker tracker
+    ) {
+        // Collect all struct names that are instantiated
+        Set<String> usedStructs = new HashSet<>();
+        for (LetStatement letStatement : program.letStatements()) {
+            usedStructs.add(letStatement.instance().definition().name());
+        }
+
+        // Check for unused struct definitions
+        for (StructDefinition structDef : program.structDefinitions()) {
+            if (!usedStructs.contains(structDef.name())) {
+                if (tracker.add(PROGRAM_WARNING_UNUSED_STRUCT.get(structDef.name())).isSaturated()) {
+                    return;
+                }
+            }
+        }
+    }
+
+    @Override
+    public void fixWarnings(
+            Program program,
+            LabelPositionHolder labels,
+            ManagerBlockEntity manager,
+            Level level,
+            ItemStack disk
+    ) {
+        // We can't auto-fix this - removing unused struct definitions would require
+        // modifying the program source code
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfm/common/program/linting/StructUsageLinter.java b/src/main/java/ca/teamdman/sfm/common/program/linting/StructUsageLinter.java
new file mode 100644
index 000000000..e6ff299ae
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfm/common/program/linting/StructUsageLinter.java
@@ -0,0 +1,92 @@
+package ca.teamdman.sfm.common.program.linting;
+
+import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
+import ca.teamdman.sfm.common.label.LabelPositionHolder;
+import ca.teamdman.sfml.ast.*;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.Level;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import static ca.teamdman.sfm.common.localization.LocalizationKeys.PROGRAM_WARNING_UNUSED_STRUCT_INSTANCE;
+
+/**
+ * Linter that validates struct instances are actually used.
+ */
+public class StructUsageLinter implements IProgramLinter {
+    @Override
+    public void gatherWarnings(
+            Program program,
+            LabelPositionHolder labelPositionHolder,
+            @Nullable ManagerBlockEntity managerBlockEntity,
+            ProblemTracker tracker
+    ) {
+        // Collect all struct instance variable names that are used in USING clauses
+        Set<String> usedInstances = new HashSet<>();
+        collectUsedInstances(program, usedInstances);
+
+        // Check for unused struct instances
+        for (LetStatement letStatement : program.letStatements()) {
+            String variableName = letStatement.variableName();
+            if (!usedInstances.contains(variableName)) {
+                if (tracker.add(PROGRAM_WARNING_UNUSED_STRUCT_INSTANCE.get(variableName)).isSaturated()) {
+                    return;
+                }
+            }
+        }
+    }
+
+    private void collectUsedInstances(ASTNode node, Set<String> usedInstances) {
+        if (node instanceof LabelAccess labelAccess) {
+            StructAccess structAccess = labelAccess.structAccess();
+            if (structAccess != null) {
+                usedInstances.add(structAccess.variableName());
+            }
+        }
+
+        // Recursively check child statements
+        for (Statement child : node.getStatements()) {
+            collectUsedInstances(child, usedInstances);
+
+            // Check label access in IO statements
+            if (child instanceof IOStatement ioStatement) {
+                LabelAccess labelAccess = ioStatement.labelAccess();
+                if (labelAccess.structAccess() != null) {
+                    usedInstances.add(labelAccess.structAccess().variableName());
+                }
+            }
+
+            // Check label access in BoolHas expressions
+            if (child instanceof IfStatement ifStatement) {
+                collectUsedInstancesFromBoolExpr(ifStatement, usedInstances);
+            }
+        }
+    }
+
+    private void collectUsedInstancesFromBoolExpr(IfStatement ifStatement, Set<String> usedInstances) {
+        // This is a simplified approach - a full implementation would need to walk
+        // the entire AST tree including all BoolExpr nodes
+        ifStatement.getDescendantStatements().forEach(stmt -> {
+            if (stmt instanceof IOStatement ioStatement) {
+                LabelAccess labelAccess = ioStatement.labelAccess();
+                if (labelAccess.structAccess() != null) {
+                    usedInstances.add(labelAccess.structAccess().variableName());
+                }
+            }
+        });
+    }
+
+    @Override
+    public void fixWarnings(
+            Program program,
+            LabelPositionHolder labels,
+            ManagerBlockEntity manager,
+            Level level,
+            ItemStack disk
+    ) {
+        // We can't auto-fix this - removing unused struct instances would require
+        // modifying the program source code
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfm/common/registry/SFMProgramLinters.java b/src/main/java/ca/teamdman/sfm/common/registry/SFMProgramLinters.java
index 584463b5a..84f21bdb8 100644
--- a/src/main/java/ca/teamdman/sfm/common/registry/SFMProgramLinters.java
+++ b/src/main/java/ca/teamdman/sfm/common/registry/SFMProgramLinters.java
@@ -69,6 +69,18 @@ public class SFMProgramLinters {
             NoSlotStatementProgramLinter::new
     );
 
+    public static final SFMRegistryObject<IProgramLinter, StructDefinitionLinter>
+            STRUCT_DEFINITION_LINTER = REGISTERER.register(
+            "struct_definition",
+            StructDefinitionLinter::new
+    );
+
+    public static final SFMRegistryObject<IProgramLinter, StructUsageLinter>
+            STRUCT_USAGE_LINTER = REGISTERER.register(
+            "struct_usage",
+            StructUsageLinter::new
+    );
+
     static {
         if (SFMModCompat.isMekanismLoaded()) {
             SFMMekanismCompat.registerProgramLinters(REGISTERER);

From 8bac6ed7fc5aaa1e9b9c17e8e3987198388f9882 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sat, 24 Jan 2026 18:51:27 +0100
Subject: [PATCH 07/33] test: add struct tests

---
 .../java/ca/teamdman/sfml/CodegenTests.java   |   2 +
 src/test/java/ca/teamdman/sfml/SFMLTests.java | 203 ++++++++++++++++++
 2 files changed, 205 insertions(+)

diff --git a/src/test/java/ca/teamdman/sfml/CodegenTests.java b/src/test/java/ca/teamdman/sfml/CodegenTests.java
index af1aa83cc..e5ab06722 100644
--- a/src/test/java/ca/teamdman/sfml/CodegenTests.java
+++ b/src/test/java/ca/teamdman/sfml/CodegenTests.java
@@ -80,6 +80,8 @@ public void codegen() {
         var program = new Program(
                 new ASTBuilder(),
                 "hello world",
+                List.of(), // structDefinitions
+                List.of(), // letStatements
                 List.of(new TimerTrigger(
                         new Interval(20, Interval.IntervalAlignment.LOCAL, 0),
                         new Block(List.of(new IfStatement(
diff --git a/src/test/java/ca/teamdman/sfml/SFMLTests.java b/src/test/java/ca/teamdman/sfml/SFMLTests.java
index 8ccfe2942..023538d0e 100644
--- a/src/test/java/ca/teamdman/sfml/SFMLTests.java
+++ b/src/test/java/ca/teamdman/sfml/SFMLTests.java
@@ -811,4 +811,207 @@ public void condensedIdentifier7() {
         assertEquals("sfm:fluid:minecraft:.*", ident.toString());
         assertEquals("fluid:minecraft:", ident.toStringCondensed());
     }
+
+    // ===== STRUCT TESTS =====
+
+    @Test
+    public void structBasicDefinition() {
+        assertNoCompileErrors(
+                """
+                        NAME "Struct Test"
+
+                        struct Furnace
+                            input: TOP SIDE SLOTS 0
+                            fuel: BOTTOM SIDE SLOTS 1
+                            output: BOTTOM SIDE SLOTS 2
+                        end
+
+                        let smelter = Furnace { label: "my_furnaces" }
+
+                        every 20 ticks do
+                            input from ore_chest
+                            output to smelter using input
+                        end
+                        """
+        );
+    }
+
+    @Test
+    public void structWithUsingClause() {
+        var input = """
+                NAME "Struct Using Test"
+
+                struct Furnace
+                    input: TOP SIDE SLOTS 0
+                    output: BOTTOM SIDE SLOTS 2
+                end
+
+                let smelter = Furnace { label: "furnaces" }
+
+                every 20 ticks do
+                    input from chest
+                    output to smelter using input
+
+                    forget
+
+                    input from smelter using output
+                    output to storage
+                end
+                """;
+        assertNoCompileErrors(input);
+        var program = compile(input);
+        assertEquals(1, program.structDefinitions().size());
+        assertEquals(1, program.letStatements().size());
+        assertEquals("Furnace", program.structDefinitions().get(0).name());
+        assertEquals("smelter", program.letStatements().get(0).variableName());
+    }
+
+    @Test
+    public void structMissingLabel() {
+        var input = """
+                NAME "Missing Label Test"
+
+                struct Furnace
+                    input: TOP SIDE
+                end
+
+                let smelter = Furnace { input: TOP SIDE }
+
+                every 20 ticks do
+                    input from chest
+                end
+                """;
+        assertCompileErrorsPresent(input);
+    }
+
+    @Test
+    public void structUnknownStruct() {
+        var input = """
+                NAME "Unknown Struct Test"
+
+                let smelter = UnknownStruct { label: "test" }
+
+                every 20 ticks do
+                    input from chest
+                end
+                """;
+        assertCompileErrorsPresent(input);
+    }
+
+    @Test
+    public void structUnknownVariable() {
+        var input = """
+                NAME "Unknown Variable Test"
+
+                struct Furnace
+                    input: TOP SIDE
+                end
+
+                let smelter = Furnace { label: "test" }
+
+                every 20 ticks do
+                    input from unknown_var using input
+                end
+                """;
+        assertCompileErrorsPresent(input);
+    }
+
+    @Test
+    public void structUnknownField() {
+        var input = """
+                NAME "Unknown Field Test"
+
+                struct Furnace
+                    input: TOP SIDE
+                end
+
+                let smelter = Furnace { label: "test" }
+
+                every 20 ticks do
+                    input from smelter using unknown_field
+                end
+                """;
+        assertCompileErrorsPresent(input);
+    }
+
+    @Test
+    public void structDuplicateDefinition() {
+        var input = """
+                NAME "Duplicate Struct Test"
+
+                struct Furnace
+                    input: TOP SIDE
+                end
+
+                struct Furnace
+                    output: BOTTOM SIDE
+                end
+
+                let smelter = Furnace { label: "test" }
+
+                every 20 ticks do
+                    input from chest
+                end
+                """;
+        assertCompileErrorsPresent(input);
+    }
+
+    @Test
+    public void structDuplicateField() {
+        var input = """
+                NAME "Duplicate Field Test"
+
+                struct Furnace
+                    input: TOP SIDE
+                    input: BOTTOM SIDE
+                end
+
+                let smelter = Furnace { label: "test" }
+
+                every 20 ticks do
+                    input from chest
+                end
+                """;
+        assertCompileErrorsPresent(input);
+    }
+
+    @Test
+    public void structSideOverride() {
+        var input = """
+                NAME "Side Override Test"
+
+                struct Furnace
+                    input: TOP SIDE SLOTS 0
+                end
+
+                let smelter = Furnace { label: "furnaces" }
+
+                every 20 ticks do
+                    input from chest
+                    output to smelter using input BOTTOM SIDE
+                end
+                """;
+        assertNoCompileErrors(input);
+    }
+
+    @Test
+    public void structSlotOnlyField() {
+        assertNoCompileErrors(
+                """
+                        NAME "Slot Only Field Test"
+
+                        struct Storage
+                            main: SLOTS 0-26
+                            hotbar: SLOTS 27-35
+                        end
+
+                        let inv = Storage { label: "inventory" }
+
+                        every 20 ticks do
+                            input from inv using main
+                            output to inv using hotbar
+                        end
+                        """
+        );
+    }
 }

From 955989458cbc2d9c2413c8d0a38f404fd76e2c83 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sat, 24 Jan 2026 20:29:00 +0100
Subject: [PATCH 08/33] feat: add protocol, macro, and library support to SFML

---
 src/main/antlr/sfml/SFML.g4                   |  71 ++-
 .../java/ca/teamdman/sfml/ast/ASTBuilder.java | 556 +++++++++++++++++-
 .../ca/teamdman/sfml/ast/ExpandArgument.java  |  33 ++
 .../ca/teamdman/sfml/ast/ExpandStatement.java |  49 ++
 .../ca/teamdman/sfml/ast/ImportStatement.java |  15 +
 .../teamdman/sfml/ast/LibraryStatement.java   |  15 +
 .../ca/teamdman/sfml/ast/MacroDefinition.java |  59 ++
 .../sfml/ast/MacroForgetStatement.java        |  12 +
 .../teamdman/sfml/ast/MacroIfStatement.java   |  30 +
 .../sfml/ast/MacroInputStatement.java         |  32 +
 .../teamdman/sfml/ast/MacroLabelAccess.java   |  58 ++
 .../sfml/ast/MacroOutputStatement.java        |  32 +
 .../ca/teamdman/sfml/ast/MacroParameter.java  |  21 +
 .../ca/teamdman/sfml/ast/MacroStatement.java  |   9 +
 .../java/ca/teamdman/sfml/ast/Program.java    |  65 ++
 .../teamdman/sfml/ast/ProtocolDefinition.java |  39 ++
 .../ca/teamdman/sfml/ast/ProtocolField.java   |  16 +
 .../teamdman/sfml/ast/ProtocolFieldType.java  |  39 ++
 .../teamdman/sfml/ast/StructDefinition.java   |  23 +-
 .../sfml/program_builder/ImportResolver.java  |  24 +
 .../program_builder/LibraryDefinitions.java   |  42 ++
 .../sfml/program_builder/LibraryResolver.java |  24 +
 22 files changed, 1252 insertions(+), 12 deletions(-)
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/ExpandArgument.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/ExpandStatement.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/ImportStatement.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/LibraryStatement.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/MacroDefinition.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/MacroForgetStatement.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/MacroIfStatement.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/MacroInputStatement.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/MacroLabelAccess.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/MacroOutputStatement.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/MacroParameter.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/MacroStatement.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/ProtocolDefinition.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/ProtocolField.java
 create mode 100644 src/main/java/ca/teamdman/sfml/ast/ProtocolFieldType.java
 create mode 100644 src/main/java/ca/teamdman/sfml/program_builder/ImportResolver.java
 create mode 100644 src/main/java/ca/teamdman/sfml/program_builder/LibraryDefinitions.java
 create mode 100644 src/main/java/ca/teamdman/sfml/program_builder/LibraryResolver.java

diff --git a/src/main/antlr/sfml/SFML.g4 b/src/main/antlr/sfml/SFML.g4
index a68fa01d9..c660060c8 100644
--- a/src/main/antlr/sfml/SFML.g4
+++ b/src/main/antlr/sfml/SFML.g4
@@ -6,7 +6,29 @@ package ca.teamdman.langs;
     public boolean INCLUDE_UNUSED = false; // we want syntax highlighting to not break on unexpected tokens
 }
 
-program : name? structDefinition* letStatement* trigger* EOF;
+program : name? import_* library* protocolDefinition* structDefinition* macroDefinition* letStatement* trigger* EOF;
+
+//
+// IMPORTS AND LIBRARIES
+//
+
+import_ : IMPORT string ;
+library : USE LIBRARY string ;
+
+//
+// PROTOCOL DEFINITIONS
+//
+
+protocolDefinition : PROTOCOL identifier protocolBody END ;
+protocolBody : protocolField* ;
+protocolField : identifier COLON protocolFieldType ;
+protocolFieldType : SIDEQUALIFIER SLOTQUALIFIER    #SideAndSlotType
+                  | SIDEQUALIFIER                  #SideType
+                  | SLOTQUALIFIER                  #SlotType
+                  | LABEL                          #LabelType
+                  | RESOURCE                       #ResourceType
+                  | NUMBERTYPE                     #NumberType
+                  ;
 
 name: NAME string ;
 
@@ -14,7 +36,7 @@ name: NAME string ;
 // STRUCT DEFINITIONS
 //
 
-structDefinition : STRUCT identifier structBody END ;
+structDefinition : STRUCT identifier (COLON identifier (COMMA identifier)*)? structBody END ;
 structBody : structField* ;
 structField : identifier COLON structFieldValue ;
 structFieldValue : sidequalifier slotqualifier?   // composite: TOP SIDE SLOTS 0
@@ -24,6 +46,28 @@ structFieldValue : sidequalifier slotqualifier?   // composite: TOP SIDE SLOTS 0
                  | number
                  ;
 
+//
+// MACRO DEFINITIONS
+//
+
+macroDefinition : MACRO identifier LPAREN macroParamList? RPAREN macroBody END ;
+macroParamList : macroParam (COMMA macroParam)* ;
+macroParam : identifier (COLON identifier)? ;
+macroBody : macroStatement* ;
+macroStatement : macroInputStatement
+               | macroOutputStatement
+               | macroIfStatement
+               | macroForgetStatement
+               ;
+macroInputStatement : INPUT macroResourceLimits? FROM EACH? macroLabelAccess ;
+macroOutputStatement : OUTPUT macroResourceLimits? TO EACH? macroLabelAccess ;
+macroIfStatement : IF boolexpr THEN macroBody (ELSE macroBody)? END ;
+macroForgetStatement : FORGET ;
+macroResourceLimits : resourceLimitList ;
+macroLabelAccess : identifier                                               #MacroParamLabelAccess
+                 | identifier USING identifier sidequalifier? slotqualifier? #MacroStructLabelAccess
+                 ;
+
 letStatement : LET identifier EQ_SYMBOL structInstantiation ;
 structInstantiation : identifier LBRACE structFieldAssignment (COMMA structFieldAssignment)* COMMA? RBRACE ;
 structFieldAssignment : identifier COLON structFieldValue ;
@@ -48,8 +92,13 @@ statement       : inputStatement
                 | outputStatement
                 | ifStatement
                 | forgetStatement
+                | expandStatement
                 ;
 
+expandStatement : EXPAND identifier LPAREN expandArgList? RPAREN ;
+expandArgList : expandArg (COMMA expandArg)* ;
+expandArg : identifier | string ;
+
 // IO STATEMENT
 forgetStatement : FORGET label? (COMMA label)* COMMA?;
 inputStatement  : INPUT inputResourceLimits? resourceExclusion? FROM EACH? labelAccess
@@ -170,7 +219,7 @@ label           : (identifier)  #RawLabel
 
 emptyslots      : EMPTY (SLOTS | SLOT) IN ;
 
-identifier : (IDENTIFIER | REDSTONE | GLOBAL | SECOND | SECONDS | TOP | BOTTOM | LEFT | RIGHT | FRONT | BACK | INPUT | OUTPUT | LABEL | STRUCT | LET | USING | SLOT | SLOTS | SIDE | BLOCK) ;
+identifier : (IDENTIFIER | REDSTONE | GLOBAL | SECOND | SECONDS | TOP | BOTTOM | LEFT | RIGHT | FRONT | BACK | INPUT | OUTPUT | LABEL | STRUCT | LET | USING | SLOT | SLOTS | SIDE | BLOCK | PROTOCOL | MACRO | EXPAND | IMPORT | USE | LIBRARY | RESOURCE | SIDEQUALIFIER | SLOTQUALIFIER | NUMBERTYPE) ;
 
 // GENERAL
 string: STRING ;
@@ -279,6 +328,22 @@ USING           : U S I N G ;
 LBRACE          : '{' ;
 RBRACE          : '}' ;
 
+// PROTOCOL SYMBOLS
+PROTOCOL        : P R O T O C O L ;
+SIDEQUALIFIER   : S I D E Q U A L I F I E R ;
+SLOTQUALIFIER   : S L O T Q U A L I F I E R ;
+RESOURCE        : R E S O U R C E ;
+NUMBERTYPE      : N U M B E R ;
+
+// MACRO SYMBOLS
+MACRO           : M A C R O ;
+EXPAND          : E X P A N D ;
+
+// IMPORT SYMBOLS
+IMPORT          : I M P O R T ;
+USE             : U S E ;
+LIBRARY         : L I B R A R Y ;
+
 // GENERAL SYMBOLS
 // used by triggers and as a set operator
 EVERY           : E V E R Y ;
diff --git a/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java b/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
index add868252..edee1c669 100644
--- a/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
+++ b/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
@@ -30,6 +30,12 @@ public class ASTBuilder extends SFMLBaseVisitor<ASTNode> {
     /// Struct instances indexed by variable name, populated during AST building
     private final Map<String, StructInstance> STRUCT_INSTANCES = new HashMap<>();
 
+    /// Protocol definitions indexed by name, populated during AST building
+    private final Map<String, ProtocolDefinition> PROTOCOL_DEFINITIONS = new HashMap<>();
+
+    /// Macro definitions indexed by name, populated during AST building
+    private final Map<String, MacroDefinition> MACRO_DEFINITIONS = new HashMap<>();
+
     /// @return hierarchy of nodes; e.g., Program > Trigger > Block > IOStatement > LabelAccess > Label
     public List<Pair<ASTNode, ParserRuleContext>> getNodesUnderCursor(int cursorPos) {
 
@@ -57,8 +63,14 @@ public void setLocationFromOtherNode(
             ASTNode node,
             ASTNode otherNode
     ) {
-
-        trackNode(node, AST_NODE_CONTEXTS.get(getIndexForNode(otherNode)).getSecond());
+        int index = getIndexForNode(otherNode);
+        if (index < 0) {
+            // Node not found in AST_NODE_CONTEXTS - this can happen for macro-expanded statements
+            // In this case, we track the node without a context
+            trackNode(node, null);
+            return;
+        }
+        trackNode(node, AST_NODE_CONTEXTS.get(index).getSecond());
     }
 
     /// Used for client-server collaboration to make context menu actions work.
@@ -182,13 +194,41 @@ public Program visitProgram(SFMLParser.ProgramContext ctx) {
         }
         var name = visitName(ctx.name());
 
-        // Process struct definitions first
+        // Process imports
+        var imports = ctx
+                .import_()
+                .stream()
+                .map(this::visitImport_)
+                .collect(Collectors.toList());
+
+        // Process library references
+        var libraries = ctx
+                .library()
+                .stream()
+                .map(this::visitLibrary)
+                .collect(Collectors.toList());
+
+        // Process protocol definitions
+        var protocolDefinitions = ctx
+                .protocolDefinition()
+                .stream()
+                .map(this::visitProtocolDefinition)
+                .collect(Collectors.toList());
+
+        // Process struct definitions (they can implement protocols)
         var structDefinitions = ctx
                 .structDefinition()
                 .stream()
                 .map(this::visitStructDefinition)
                 .collect(Collectors.toList());
 
+        // Process macro definitions (they can reference protocols)
+        var macroDefinitions = ctx
+                .macroDefinition()
+                .stream()
+                .map(this::visitMacroDefinition)
+                .collect(Collectors.toList());
+
         // Process let statements next (they reference struct definitions)
         var letStatements = ctx
                 .letStatement()
@@ -196,7 +236,7 @@ public Program visitProgram(SFMLParser.ProgramContext ctx) {
                 .map(this::visitLetStatement)
                 .collect(Collectors.toList());
 
-        // Process triggers last (they can reference struct instances)
+        // Process triggers last (they can reference struct instances and macros)
         var triggers = ctx
                 .trigger()
                 .stream()
@@ -208,21 +248,120 @@ public Program visitProgram(SFMLParser.ProgramContext ctx) {
                 .stream()
                 .map(Label::name)
                 .collect(Collectors.toSet());
-        Program program = new Program(this, name.value(), structDefinitions, letStatements, triggers, labels, USED_RESOURCES);
+        Program program = new Program(
+                this,
+                name.value(),
+                imports,
+                libraries,
+                protocolDefinitions,
+                structDefinitions,
+                macroDefinitions,
+                letStatements,
+                triggers,
+                labels,
+                USED_RESOURCES
+        );
         trackNode(program, ctx);
         return program;
     }
 
+    // ===== IMPORTS AND LIBRARIES =====
+
+    public ImportStatement visitImport_(SFMLParser.Import_Context ctx) {
+        String path = visitString(ctx.string()).value();
+        ImportStatement importStmt = new ImportStatement(path);
+        trackNode(importStmt, ctx);
+        return importStmt;
+    }
+
+    public LibraryStatement visitLibrary(SFMLParser.LibraryContext ctx) {
+        String blockLabel = visitString(ctx.string()).value();
+        LibraryStatement libraryStmt = new LibraryStatement(blockLabel);
+        trackNode(libraryStmt, ctx);
+        return libraryStmt;
+    }
+
+    // ===== PROTOCOL DEFINITIONS =====
+
+    public ProtocolDefinition visitProtocolDefinition(SFMLParser.ProtocolDefinitionContext ctx) {
+        String name = ctx.identifier().getText();
+
+        // Check for duplicate protocol names
+        if (PROTOCOL_DEFINITIONS.containsKey(name)) {
+            throw new IllegalArgumentException("Duplicate protocol definition: " + name);
+        }
+
+        List<ProtocolField> fields = new ArrayList<>();
+        Set<String> fieldNames = new HashSet<>();
+
+        for (SFMLParser.ProtocolFieldContext fieldCtx : ctx.protocolBody().protocolField()) {
+            ProtocolField field = visitProtocolField(fieldCtx);
+
+            // Check for duplicate field names
+            if (!fieldNames.add(field.name())) {
+                throw new IllegalArgumentException(
+                        "Duplicate field name '" + field.name() + "' in protocol " + name
+                );
+            }
+
+            fields.add(field);
+        }
+
+        ProtocolDefinition protocolDef = new ProtocolDefinition(name, fields);
+        PROTOCOL_DEFINITIONS.put(name, protocolDef);
+        trackNode(protocolDef, ctx);
+        return protocolDef;
+    }
+
+    public ProtocolField visitProtocolField(SFMLParser.ProtocolFieldContext ctx) {
+        String fieldName = ctx.identifier().getText();
+        ProtocolFieldType type = visitProtocolFieldType(ctx.protocolFieldType());
+        ProtocolField field = new ProtocolField(fieldName, type);
+        trackNode(field, ctx);
+        return field;
+    }
+
+    public ProtocolFieldType visitProtocolFieldType(SFMLParser.ProtocolFieldTypeContext ctx) {
+        ProtocolFieldType type;
+        if (ctx instanceof SFMLParser.SideAndSlotTypeContext) {
+            type = ProtocolFieldType.SIDE_AND_SLOT;
+        } else if (ctx instanceof SFMLParser.SideTypeContext) {
+            type = ProtocolFieldType.SIDE_QUALIFIER;
+        } else if (ctx instanceof SFMLParser.SlotTypeContext) {
+            type = ProtocolFieldType.SLOT_QUALIFIER;
+        } else if (ctx instanceof SFMLParser.LabelTypeContext) {
+            type = ProtocolFieldType.LABEL;
+        } else if (ctx instanceof SFMLParser.ResourceTypeContext) {
+            type = ProtocolFieldType.RESOURCE;
+        } else if (ctx instanceof SFMLParser.NumberTypeContext) {
+            type = ProtocolFieldType.NUMBER;
+        } else {
+            throw new IllegalStateException("Unknown protocol field type");
+        }
+        trackNode(type, ctx);
+        return type;
+    }
+
     // ===== STRUCT DEFINITIONS =====
 
     public StructDefinition visitStructDefinition(SFMLParser.StructDefinitionContext ctx) {
-        String name = ctx.identifier().getText();
+        String name = ctx.identifier(0).getText();
 
         // Check for duplicate struct names
         if (STRUCT_DEFINITIONS.containsKey(name)) {
             throw new IllegalArgumentException("Duplicate struct definition: " + name);
         }
 
+        // Collect implemented protocols
+        List<String> implementedProtocols = new ArrayList<>();
+        for (int i = 1; i < ctx.identifier().size(); i++) {
+            String protocolName = ctx.identifier(i).getText();
+            if (!PROTOCOL_DEFINITIONS.containsKey(protocolName)) {
+                throw new IllegalArgumentException("Unknown protocol: " + protocolName);
+            }
+            implementedProtocols.add(protocolName);
+        }
+
         List<StructField> fields = new ArrayList<>();
         Set<String> fieldNames = new HashSet<>();
 
@@ -239,12 +378,42 @@ public StructDefinition visitStructDefinition(SFMLParser.StructDefinitionContext
             fields.add(field);
         }
 
-        StructDefinition structDef = new StructDefinition(name, fields);
+        StructDefinition structDef = new StructDefinition(name, implementedProtocols, fields);
+
+        // Validate protocol conformance
+        for (String protocolName : implementedProtocols) {
+            validateProtocolConformance(structDef, PROTOCOL_DEFINITIONS.get(protocolName));
+        }
+
         STRUCT_DEFINITIONS.put(name, structDef);
         trackNode(structDef, ctx);
         return structDef;
     }
 
+    /**
+     * Validates that a struct properly implements all fields required by a protocol.
+     */
+    private void validateProtocolConformance(StructDefinition struct, ProtocolDefinition protocol) {
+        for (ProtocolField protoField : protocol.fields()) {
+            Optional<StructField> structField = struct.getField(protoField.name());
+
+            if (structField.isEmpty()) {
+                throw new IllegalArgumentException(
+                        "Struct '" + struct.name() + "' is missing required field '"
+                        + protoField.name() + "' from protocol '" + protocol.name() + "'"
+                );
+            }
+
+            if (!protoField.type().matches(structField.get().value())) {
+                throw new IllegalArgumentException(
+                        "Struct '" + struct.name() + "' field '" + protoField.name()
+                        + "' has wrong type. Expected " + protoField.type()
+                        + " but got " + structField.get().value().getClass().getSimpleName()
+                );
+            }
+        }
+    }
+
     public StructField visitStructField(SFMLParser.StructFieldContext ctx) {
         String fieldName = ctx.identifier().getText();
         StructFieldValue value = visitStructFieldValue(ctx.structFieldValue());
@@ -359,6 +528,379 @@ private Map.Entry<String, StructFieldValue> parseStructFieldAssignment(SFMLParse
 
     // ===== END STRUCT DEFINITIONS =====
 
+    // ===== MACRO DEFINITIONS =====
+
+    public MacroDefinition visitMacroDefinition(SFMLParser.MacroDefinitionContext ctx) {
+        String name = ctx.identifier().getText();
+
+        // Check for duplicate macro names
+        if (MACRO_DEFINITIONS.containsKey(name)) {
+            throw new IllegalArgumentException("Duplicate macro definition: " + name);
+        }
+
+        // Parse parameters
+        List<MacroParameter> parameters = new ArrayList<>();
+        if (ctx.macroParamList() != null) {
+            for (SFMLParser.MacroParamContext paramCtx : ctx.macroParamList().macroParam()) {
+                MacroParameter param = visitMacroParam(paramCtx);
+                parameters.add(param);
+            }
+        }
+
+        // Parse body
+        List<MacroStatement> body = visitMacroBodyStatements(ctx.macroBody());
+
+        MacroDefinition macroDef = new MacroDefinition(name, parameters, body);
+        MACRO_DEFINITIONS.put(name, macroDef);
+        trackNode(macroDef, ctx);
+        return macroDef;
+    }
+
+    public MacroParameter visitMacroParam(SFMLParser.MacroParamContext ctx) {
+        String name = ctx.identifier(0).getText();
+        String protocolConstraint = null;
+        if (ctx.identifier().size() > 1) {
+            protocolConstraint = ctx.identifier(1).getText();
+            // Validate that the protocol exists
+            if (!PROTOCOL_DEFINITIONS.containsKey(protocolConstraint)) {
+                throw new IllegalArgumentException("Unknown protocol constraint: " + protocolConstraint);
+            }
+        }
+        MacroParameter param = new MacroParameter(name, protocolConstraint);
+        trackNode(param, ctx);
+        return param;
+    }
+
+    private List<MacroStatement> visitMacroBodyStatements(SFMLParser.MacroBodyContext ctx) {
+        List<MacroStatement> statements = new ArrayList<>();
+        for (SFMLParser.MacroStatementContext stmtCtx : ctx.macroStatement()) {
+            statements.add(visitMacroStatement(stmtCtx));
+        }
+        return statements;
+    }
+
+    public MacroStatement visitMacroStatement(SFMLParser.MacroStatementContext ctx) {
+        if (ctx.macroInputStatement() != null) {
+            return visitMacroInputStatement(ctx.macroInputStatement());
+        } else if (ctx.macroOutputStatement() != null) {
+            return visitMacroOutputStatement(ctx.macroOutputStatement());
+        } else if (ctx.macroIfStatement() != null) {
+            return visitMacroIfStatement(ctx.macroIfStatement());
+        } else if (ctx.macroForgetStatement() != null) {
+            return visitMacroForgetStatement(ctx.macroForgetStatement());
+        }
+        throw new IllegalStateException("Unknown macro statement type");
+    }
+
+    public MacroInputStatement visitMacroInputStatement(SFMLParser.MacroInputStatementContext ctx) {
+        MacroLabelAccess labelAccess = visitMacroLabelAccess(ctx.macroLabelAccess());
+        ResourceLimits resourceLimits = null;
+        if (ctx.macroResourceLimits() != null) {
+            resourceLimits = visitResourceLimitList(ctx.macroResourceLimits().resourceLimitList())
+                    .withDefaultLimit(Limit.MAX_QUANTITY_NO_RETENTION);
+        }
+        boolean each = ctx.EACH() != null;
+        MacroInputStatement stmt = new MacroInputStatement(labelAccess, resourceLimits, each);
+        trackNode(stmt, ctx);
+        return stmt;
+    }
+
+    public MacroOutputStatement visitMacroOutputStatement(SFMLParser.MacroOutputStatementContext ctx) {
+        MacroLabelAccess labelAccess = visitMacroLabelAccess(ctx.macroLabelAccess());
+        ResourceLimits resourceLimits = null;
+        if (ctx.macroResourceLimits() != null) {
+            resourceLimits = visitResourceLimitList(ctx.macroResourceLimits().resourceLimitList())
+                    .withDefaultLimit(Limit.MAX_QUANTITY_MAX_RETENTION);
+        }
+        boolean each = ctx.EACH() != null;
+        MacroOutputStatement stmt = new MacroOutputStatement(labelAccess, resourceLimits, each);
+        trackNode(stmt, ctx);
+        return stmt;
+    }
+
+    public MacroIfStatement visitMacroIfStatement(SFMLParser.MacroIfStatementContext ctx) {
+        BoolExpr condition = (BoolExpr) visit(ctx.boolexpr());
+        List<MacroStatement> thenBody = visitMacroBodyStatements(ctx.macroBody(0));
+        List<MacroStatement> elseBody = ctx.macroBody().size() > 1
+                ? visitMacroBodyStatements(ctx.macroBody(1))
+                : List.of();
+        MacroIfStatement stmt = new MacroIfStatement(condition, thenBody, elseBody);
+        trackNode(stmt, ctx);
+        return stmt;
+    }
+
+    public MacroForgetStatement visitMacroForgetStatement(SFMLParser.MacroForgetStatementContext ctx) {
+        MacroForgetStatement stmt = new MacroForgetStatement();
+        trackNode(stmt, ctx);
+        return stmt;
+    }
+
+    public MacroLabelAccess visitMacroLabelAccess(SFMLParser.MacroLabelAccessContext ctx) {
+        if (ctx instanceof SFMLParser.MacroParamLabelAccessContext paramCtx) {
+            String paramName = paramCtx.identifier().getText();
+            MacroLabelAccess access = MacroLabelAccess.parameter(paramName);
+            trackNode(access, ctx);
+            return access;
+        } else if (ctx instanceof SFMLParser.MacroStructLabelAccessContext structCtx) {
+            String paramName = structCtx.identifier(0).getText();
+            String fieldName = structCtx.identifier(1).getText();
+            SideQualifier sideOverride = structCtx.sidequalifier() != null
+                    ? (SideQualifier) visit(structCtx.sidequalifier())
+                    : null;
+            NumberRangeSet slotOverride = structCtx.slotqualifier() != null
+                    ? visitSlotqualifier(structCtx.slotqualifier())
+                    : null;
+            MacroLabelAccess access = MacroLabelAccess.structAccess(paramName, fieldName, sideOverride, slotOverride);
+            trackNode(access, ctx);
+            return access;
+        }
+        throw new IllegalStateException("Unknown macro label access type");
+    }
+
+    // ===== EXPAND STATEMENTS =====
+
+    @Override
+    public ExpandStatement visitExpandStatement(SFMLParser.ExpandStatementContext ctx) {
+        String macroName = ctx.identifier().getText();
+
+        // Look up the macro
+        MacroDefinition macro = MACRO_DEFINITIONS.get(macroName);
+        if (macro == null) {
+            throw new IllegalArgumentException("Unknown macro: " + macroName);
+        }
+
+        // Parse arguments
+        List<ExpandArgument> arguments = new ArrayList<>();
+        if (ctx.expandArgList() != null) {
+            for (SFMLParser.ExpandArgContext argCtx : ctx.expandArgList().expandArg()) {
+                ExpandArgument arg = visitExpandArg(argCtx);
+                arguments.add(arg);
+            }
+        }
+
+        // Validate argument count
+        if (arguments.size() != macro.parameters().size()) {
+            throw new IllegalArgumentException(
+                    "Macro '" + macroName + "' expects " + macro.parameters().size()
+                    + " arguments but got " + arguments.size()
+            );
+        }
+
+        // Validate protocol constraints
+        for (int i = 0; i < arguments.size(); i++) {
+            MacroParameter param = macro.parameters().get(i);
+            ExpandArgument arg = arguments.get(i);
+
+            if (param.protocolConstraint() != null) {
+                // Argument must be a struct variable that implements the protocol
+                if (arg.isStringLiteral()) {
+                    throw new IllegalArgumentException(
+                            "Macro parameter '" + param.name() + "' requires a struct implementing protocol '"
+                            + param.protocolConstraint() + "', but got a string literal"
+                    );
+                }
+
+                StructInstance instance = STRUCT_INSTANCES.get(arg.value());
+                if (instance == null) {
+                    throw new IllegalArgumentException(
+                            "Macro parameter '" + param.name() + "' requires a struct implementing protocol '"
+                            + param.protocolConstraint() + "', but '" + arg.value() + "' is not a struct variable"
+                    );
+                }
+
+                if (!instance.definition().implementsProtocol(param.protocolConstraint())) {
+                    throw new IllegalArgumentException(
+                            "Struct '" + instance.definition().name() + "' does not implement protocol '"
+                            + param.protocolConstraint() + "' required by macro parameter '" + param.name() + "'"
+                    );
+                }
+            }
+        }
+
+        // Expand the macro
+        List<Statement> expandedStatements = expandMacro(macro, arguments);
+
+        ExpandStatement expandStmt = new ExpandStatement(macroName, arguments, expandedStatements);
+        trackNode(expandStmt, ctx);
+        return expandStmt;
+    }
+
+    public ExpandArgument visitExpandArg(SFMLParser.ExpandArgContext ctx) {
+        if (ctx.identifier() != null) {
+            return ExpandArgument.identifier(ctx.identifier().getText());
+        } else if (ctx.string() != null) {
+            return ExpandArgument.stringLiteral(visitString(ctx.string()).value());
+        }
+        throw new IllegalStateException("Unknown expand argument type");
+    }
+
+    /**
+     * Expands a macro with the given arguments, producing a list of statements.
+     */
+    private List<Statement> expandMacro(MacroDefinition macro, List<ExpandArgument> arguments) {
+        List<Statement> result = new ArrayList<>();
+
+        // Build argument map
+        Map<String, ExpandArgument> argMap = new HashMap<>();
+        for (int i = 0; i < macro.parameters().size(); i++) {
+            argMap.put(macro.parameters().get(i).name(), arguments.get(i));
+        }
+
+        // Expand each macro statement
+        for (MacroStatement macroStmt : macro.body()) {
+            result.addAll(expandMacroStatement(macroStmt, argMap));
+        }
+
+        return result;
+    }
+
+    /**
+     * Expands a single macro statement into regular statements.
+     */
+    private List<Statement> expandMacroStatement(MacroStatement macroStmt, Map<String, ExpandArgument> argMap) {
+        if (macroStmt instanceof MacroInputStatement input) {
+            return List.of(expandMacroInput(input, argMap));
+        } else if (macroStmt instanceof MacroOutputStatement output) {
+            return List.of(expandMacroOutput(output, argMap));
+        } else if (macroStmt instanceof MacroForgetStatement) {
+            return List.of(new ForgetStatement(USED_LABELS));
+        } else if (macroStmt instanceof MacroIfStatement macroIf) {
+            List<Statement> thenStatements = new ArrayList<>();
+            for (MacroStatement s : macroIf.thenBody()) {
+                thenStatements.addAll(expandMacroStatement(s, argMap));
+            }
+            List<Statement> elseStatements = new ArrayList<>();
+            for (MacroStatement s : macroIf.elseBody()) {
+                elseStatements.addAll(expandMacroStatement(s, argMap));
+            }
+            return List.of(new IfStatement(
+                    macroIf.condition(),
+                    new Block(thenStatements),
+                    new Block(elseStatements)
+            ));
+        }
+        throw new IllegalStateException("Unknown macro statement type: " + macroStmt.getClass());
+    }
+
+    /**
+     * Expands a macro input statement.
+     */
+    private InputStatement expandMacroInput(MacroInputStatement macroInput, Map<String, ExpandArgument> argMap) {
+        LabelAccess labelAccess = resolveMacroLabelAccess(macroInput.labelAccess(), argMap);
+        ResourceLimits limits = macroInput.resourceLimits() != null
+                ? macroInput.resourceLimits()
+                : new ResourceLimits(List.of(ResourceLimit.TAKE_ALL_LEAVE_NONE), ResourceIdSet.EMPTY);
+        return new InputStatement(labelAccess, limits, macroInput.each());
+    }
+
+    /**
+     * Expands a macro output statement.
+     */
+    private OutputStatement expandMacroOutput(MacroOutputStatement macroOutput, Map<String, ExpandArgument> argMap) {
+        LabelAccess labelAccess = resolveMacroLabelAccess(macroOutput.labelAccess(), argMap);
+        ResourceLimits limits = macroOutput.resourceLimits() != null
+                ? macroOutput.resourceLimits()
+                : new ResourceLimits(List.of(ResourceLimit.ACCEPT_ALL_WITHOUT_RESTRAINT), ResourceIdSet.EMPTY);
+        return new OutputStatement(labelAccess, limits, macroOutput.each(), false);
+    }
+
+    /**
+     * Resolves a macro label access to a concrete LabelAccess.
+     */
+    private LabelAccess resolveMacroLabelAccess(MacroLabelAccess macroAccess, Map<String, ExpandArgument> argMap) {
+        ExpandArgument arg = argMap.get(macroAccess.parameterOrVariable());
+
+        if (macroAccess.isStructAccess()) {
+            // This is a struct field access: param using field
+            if (arg == null || arg.isStringLiteral()) {
+                throw new IllegalStateException(
+                        "Macro struct access requires a struct variable, got: " + macroAccess.parameterOrVariable()
+                );
+            }
+
+            StructInstance instance = STRUCT_INSTANCES.get(arg.value());
+            if (instance == null) {
+                throw new IllegalStateException("Unknown struct variable in macro expansion: " + arg.value());
+            }
+
+            Label label = instance.getLabel().orElseThrow(() ->
+                    new IllegalStateException("Struct instance " + arg.value() + " has no label")
+            );
+
+            // Resolve sides and slots from the field
+            String fieldName = macroAccess.fieldName();
+            Optional<StructFieldValue> fieldValue = instance.resolveField(fieldName);
+            if (fieldValue.isEmpty()) {
+                throw new IllegalStateException(
+                        "Unknown field '" + fieldName + "' in struct " + instance.definition().name()
+                );
+            }
+
+            SideQualifier sides = SideQualifier.NULL;
+            NumberRangeSet slots = NumberRangeSet.MAX_RANGE;
+
+            StructFieldValue resolved = fieldValue.get();
+            if (resolved instanceof CompositeFieldValue composite) {
+                sides = composite.sides();
+                slots = composite.slots();
+            } else if (resolved instanceof SideQualifier sq) {
+                sides = sq;
+            } else if (resolved instanceof NumberRangeSet nrs) {
+                slots = nrs;
+            }
+
+            // Apply overrides
+            if (macroAccess.sideOverride() != null) {
+                sides = macroAccess.sideOverride();
+            }
+            if (macroAccess.slotOverride() != null) {
+                slots = macroAccess.slotOverride();
+            }
+
+            return new LabelAccess(
+                    List.of(label),
+                    sides,
+                    slots,
+                    RoundRobin.disabled(),
+                    new StructAccess(arg.value(), fieldName)
+            );
+        } else {
+            // This is a simple parameter reference
+            if (arg == null) {
+                throw new IllegalStateException("Unknown macro parameter: " + macroAccess.parameterOrVariable());
+            }
+
+            Label label;
+            if (arg.isStringLiteral()) {
+                // String literal becomes a label directly
+                label = new Label(arg.value());
+                USED_LABELS.add(label);
+            } else {
+                // Check if it's a struct variable or a plain label
+                StructInstance instance = STRUCT_INSTANCES.get(arg.value());
+                if (instance != null) {
+                    label = instance.getLabel().orElseThrow(() ->
+                            new IllegalStateException("Struct instance " + arg.value() + " has no label")
+                    );
+                } else {
+                    // Treat as a label name
+                    label = new Label(arg.value());
+                    USED_LABELS.add(label);
+                }
+            }
+
+            return new LabelAccess(
+                    List.of(label),
+                    SideQualifier.NULL,
+                    NumberRangeSet.MAX_RANGE,
+                    RoundRobin.disabled(),
+                    null
+            );
+        }
+    }
+
+    // ===== END MACRO DEFINITIONS =====
+
     @Override
     public ASTNode visitTimerTrigger(SFMLParser.TimerTriggerContext ctx) {
         // create timer trigger
diff --git a/src/main/java/ca/teamdman/sfml/ast/ExpandArgument.java b/src/main/java/ca/teamdman/sfml/ast/ExpandArgument.java
new file mode 100644
index 000000000..f25f2202f
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/ExpandArgument.java
@@ -0,0 +1,33 @@
+package ca.teamdman.sfml.ast;
+
+/**
+ * Represents an argument in an expand statement.
+ * Can be either an identifier (struct variable or label) or a string literal.
+ */
+public record ExpandArgument(
+        String value,
+        boolean isStringLiteral
+) implements ASTNode {
+
+    /**
+     * Creates an identifier argument.
+     */
+    public static ExpandArgument identifier(String value) {
+        return new ExpandArgument(value, false);
+    }
+
+    /**
+     * Creates a string literal argument.
+     */
+    public static ExpandArgument stringLiteral(String value) {
+        return new ExpandArgument(value, true);
+    }
+
+    @Override
+    public String toString() {
+        if (isStringLiteral) {
+            return "\"" + value + "\"";
+        }
+        return value;
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/ExpandStatement.java b/src/main/java/ca/teamdman/sfml/ast/ExpandStatement.java
new file mode 100644
index 000000000..f91d9e9fc
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/ExpandStatement.java
@@ -0,0 +1,49 @@
+package ca.teamdman.sfml.ast;
+
+import ca.teamdman.sfm.common.program.ProgramContext;
+
+import java.util.List;
+
+/**
+ * Represents an expand statement that invokes a macro.
+ * Example: {@code expand smelt(furnace, ore_chest, ingot_chest)}
+ * <p>
+ * Macros are expanded at compile time (during AST building). The {@code expandedStatements}
+ * field contains the result of macro expansion - concrete InputStatement, OutputStatement,
+ * ForgetStatement, and IfStatement instances with parameters substituted.
+ *
+ * @param macroName          The name of the macro being expanded
+ * @param arguments          The arguments passed to the macro
+ * @param expandedStatements The statements produced by macro expansion (populated at compile time)
+ */
+public record ExpandStatement(
+        String macroName,
+        List<ExpandArgument> arguments,
+        List<Statement> expandedStatements
+) implements Statement {
+
+    @Override
+    public void tick(ProgramContext context) {
+        // Execute the expanded statements
+        for (Statement statement : expandedStatements) {
+            statement.tick(context);
+        }
+    }
+
+    @Override
+    public List<Statement> getStatements() {
+        return expandedStatements;
+    }
+
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder("expand ");
+        sb.append(macroName).append("(");
+        for (int i = 0; i < arguments.size(); i++) {
+            if (i > 0) sb.append(", ");
+            sb.append(arguments.get(i));
+        }
+        sb.append(")");
+        return sb.toString();
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/ImportStatement.java b/src/main/java/ca/teamdman/sfml/ast/ImportStatement.java
new file mode 100644
index 000000000..db7be02a2
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/ImportStatement.java
@@ -0,0 +1,15 @@
+package ca.teamdman.sfml.ast;
+
+/**
+ * Represents an import statement for file imports.
+ * Example: import "machines.sfml"
+ */
+public record ImportStatement(
+        String path
+) implements ASTNode {
+
+    @Override
+    public String toString() {
+        return "import \"" + path + "\"";
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/LibraryStatement.java b/src/main/java/ca/teamdman/sfml/ast/LibraryStatement.java
new file mode 100644
index 000000000..7e939da4c
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/LibraryStatement.java
@@ -0,0 +1,15 @@
+package ca.teamdman.sfml.ast;
+
+/**
+ * Represents a library usage statement for referencing library blocks.
+ * Example: use library "factory_config"
+ */
+public record LibraryStatement(
+        String blockLabel
+) implements ASTNode {
+
+    @Override
+    public String toString() {
+        return "use library \"" + blockLabel + "\"";
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/MacroDefinition.java b/src/main/java/ca/teamdman/sfml/ast/MacroDefinition.java
new file mode 100644
index 000000000..c6007c87c
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/MacroDefinition.java
@@ -0,0 +1,59 @@
+package ca.teamdman.sfml.ast;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * Represents a macro definition in the program.
+ * Example:
+ * macro smelt(machine: Smeltable, source, dest)
+ *     input from source
+ *     output to machine using input
+ *     forget
+ *     input from machine using output
+ *     output to dest
+ * end
+ */
+public record MacroDefinition(
+        String name,
+        List<MacroParameter> parameters,
+        List<MacroStatement> body
+) implements ASTNode {
+
+    /**
+     * Gets a parameter by name.
+     */
+    public Optional<MacroParameter> getParameter(String paramName) {
+        return parameters.stream()
+                .filter(p -> p.name().equals(paramName))
+                .findFirst();
+    }
+
+    /**
+     * Gets the index of a parameter by name.
+     */
+    public int getParameterIndex(String paramName) {
+        for (int i = 0; i < parameters.size(); i++) {
+            if (parameters.get(i).name().equals(paramName)) {
+                return i;
+            }
+        }
+        return -1;
+    }
+
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder();
+        sb.append("macro ").append(name).append("(");
+        for (int i = 0; i < parameters.size(); i++) {
+            if (i > 0) sb.append(", ");
+            sb.append(parameters.get(i));
+        }
+        sb.append(")\n");
+        for (MacroStatement stmt : body) {
+            sb.append("    ").append(stmt).append("\n");
+        }
+        sb.append("end");
+        return sb.toString();
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/MacroForgetStatement.java b/src/main/java/ca/teamdman/sfml/ast/MacroForgetStatement.java
new file mode 100644
index 000000000..1e100dabc
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/MacroForgetStatement.java
@@ -0,0 +1,12 @@
+package ca.teamdman.sfml.ast;
+
+/**
+ * Represents a forget statement within a macro body.
+ */
+public record MacroForgetStatement() implements MacroStatement {
+
+    @Override
+    public String toString() {
+        return "forget";
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/MacroIfStatement.java b/src/main/java/ca/teamdman/sfml/ast/MacroIfStatement.java
new file mode 100644
index 000000000..1b4628148
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/MacroIfStatement.java
@@ -0,0 +1,30 @@
+package ca.teamdman.sfml.ast;
+
+import java.util.List;
+
+/**
+ * Represents an if statement within a macro body.
+ */
+public record MacroIfStatement(
+        BoolExpr condition,
+        List<MacroStatement> thenBody,
+        List<MacroStatement> elseBody
+) implements MacroStatement {
+
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder("if ");
+        sb.append(condition).append(" then\n");
+        for (MacroStatement stmt : thenBody) {
+            sb.append("    ").append(stmt).append("\n");
+        }
+        if (!elseBody.isEmpty()) {
+            sb.append("else\n");
+            for (MacroStatement stmt : elseBody) {
+                sb.append("    ").append(stmt).append("\n");
+            }
+        }
+        sb.append("end");
+        return sb.toString();
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/MacroInputStatement.java b/src/main/java/ca/teamdman/sfml/ast/MacroInputStatement.java
new file mode 100644
index 000000000..dc06b45a2
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/MacroInputStatement.java
@@ -0,0 +1,32 @@
+package ca.teamdman.sfml.ast;
+
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents an input statement within a macro body.
+ * Example: {@code input 64 iron from source} or {@code input from each machine using input}
+ *
+ * @param labelAccess     The label access (parameter reference or struct field access)
+ * @param resourceLimits  Optional resource limits (quantity, retention, resource patterns)
+ * @param each            Whether to iterate over each matching inventory separately
+ */
+public record MacroInputStatement(
+        MacroLabelAccess labelAccess,
+        @Nullable ResourceLimits resourceLimits,
+        boolean each
+) implements MacroStatement {
+
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder("input");
+        if (resourceLimits != null) {
+            sb.append(" ").append(resourceLimits);
+        }
+        sb.append(" from");
+        if (each) {
+            sb.append(" each");
+        }
+        sb.append(" ").append(labelAccess);
+        return sb.toString();
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/MacroLabelAccess.java b/src/main/java/ca/teamdman/sfml/ast/MacroLabelAccess.java
new file mode 100644
index 000000000..c924499b7
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/MacroLabelAccess.java
@@ -0,0 +1,58 @@
+package ca.teamdman.sfml.ast;
+
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents a label access in a macro.
+ * Can be either:
+ * - A parameter reference (e.g., "source")
+ * - A struct field access (e.g., "machine using input")
+ */
+public record MacroLabelAccess(
+        String parameterOrVariable,
+        @Nullable String fieldName,
+        @Nullable SideQualifier sideOverride,
+        @Nullable NumberRangeSet slotOverride
+) implements ASTNode {
+
+    /**
+     * Creates a simple parameter reference.
+     */
+    public static MacroLabelAccess parameter(String parameterName) {
+        return new MacroLabelAccess(parameterName, null, null, null);
+    }
+
+    /**
+     * Creates a struct field access.
+     */
+    public static MacroLabelAccess structAccess(
+            String parameterName,
+            String fieldName,
+            @Nullable SideQualifier sideOverride,
+            @Nullable NumberRangeSet slotOverride
+    ) {
+        return new MacroLabelAccess(parameterName, fieldName, sideOverride, slotOverride);
+    }
+
+    /**
+     * Returns true if this is a struct field access.
+     */
+    public boolean isStructAccess() {
+        return fieldName != null;
+    }
+
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder(parameterOrVariable);
+        if (fieldName != null) {
+            sb.append(" using ").append(fieldName);
+        }
+        if (sideOverride != null) {
+            sb.append(" ").append(sideOverride);
+        }
+        if (slotOverride != null && !slotOverride.equals(NumberRangeSet.MAX_RANGE)) {
+            sb.append(" ").append(slotOverride);
+        }
+        return sb.toString();
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/MacroOutputStatement.java b/src/main/java/ca/teamdman/sfml/ast/MacroOutputStatement.java
new file mode 100644
index 000000000..76957eb30
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/MacroOutputStatement.java
@@ -0,0 +1,32 @@
+package ca.teamdman.sfml.ast;
+
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents an output statement within a macro body.
+ * Example: {@code output 64 iron to dest} or {@code output retain 2 to each machine using output}
+ *
+ * @param labelAccess     The label access (parameter reference or struct field access)
+ * @param resourceLimits  Optional resource limits (quantity, retention, resource patterns)
+ * @param each            Whether to iterate over each matching inventory separately
+ */
+public record MacroOutputStatement(
+        MacroLabelAccess labelAccess,
+        @Nullable ResourceLimits resourceLimits,
+        boolean each
+) implements MacroStatement {
+
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder("output");
+        if (resourceLimits != null) {
+            sb.append(" ").append(resourceLimits);
+        }
+        sb.append(" to");
+        if (each) {
+            sb.append(" each");
+        }
+        sb.append(" ").append(labelAccess);
+        return sb.toString();
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/MacroParameter.java b/src/main/java/ca/teamdman/sfml/ast/MacroParameter.java
new file mode 100644
index 000000000..b5223a280
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/MacroParameter.java
@@ -0,0 +1,21 @@
+package ca.teamdman.sfml.ast;
+
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents a parameter in a macro definition.
+ * Example: machine: Smeltable
+ */
+public record MacroParameter(
+        String name,
+        @Nullable String protocolConstraint
+) implements ASTNode {
+
+    @Override
+    public String toString() {
+        if (protocolConstraint != null) {
+            return name + ": " + protocolConstraint;
+        }
+        return name;
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/MacroStatement.java b/src/main/java/ca/teamdman/sfml/ast/MacroStatement.java
new file mode 100644
index 000000000..fb1f3160b
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/MacroStatement.java
@@ -0,0 +1,9 @@
+package ca.teamdman.sfml.ast;
+
+/**
+ * Marker interface for statements that can appear inside a macro body.
+ * Sealed to MacroInputStatement, MacroOutputStatement, MacroIfStatement, MacroForgetStatement.
+ */
+public sealed interface MacroStatement extends ASTNode
+        permits MacroInputStatement, MacroOutputStatement, MacroIfStatement, MacroForgetStatement {
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/Program.java b/src/main/java/ca/teamdman/sfml/ast/Program.java
index 127dd09fd..e63b4a0d3 100644
--- a/src/main/java/ca/teamdman/sfml/ast/Program.java
+++ b/src/main/java/ca/teamdman/sfml/ast/Program.java
@@ -34,8 +34,16 @@ public record Program(
 
         String name,
 
+        List<ImportStatement> imports,
+
+        List<LibraryStatement> libraries,
+
+        List<ProtocolDefinition> protocolDefinitions,
+
         List<StructDefinition> structDefinitions,
 
+        List<MacroDefinition> macroDefinitions,
+
         List<LetStatement> letStatements,
 
         List<Trigger> triggers,
@@ -44,6 +52,33 @@ public record Program(
 
         Set<ResourceIdentifier<?, ?, ?>> referencedResources
 ) implements Statement {
+
+    /**
+     * Backward-compatible constructor for programs without protocols, macros, imports, or libraries.
+     */
+    public Program(
+            ASTBuilder astBuilder,
+            String name,
+            List<StructDefinition> structDefinitions,
+            List<LetStatement> letStatements,
+            List<Trigger> triggers,
+            Set<String> referencedLabels,
+            Set<ResourceIdentifier<?, ?, ?>> referencedResources
+    ) {
+        this(
+                astBuilder,
+                name,
+                List.of(),
+                List.of(),
+                List.of(),
+                structDefinitions,
+                List.of(),
+                letStatements,
+                triggers,
+                referencedLabels,
+                referencedResources
+        );
+    }
     /**
      * This comes from {@link java.io.DataOutputStream#writeUTF(String, DataOutput)}
      * and {@link NetworkHooks#openScreen(ServerPlayer, MenuProvider, Consumer)}
@@ -172,6 +207,15 @@ public int getConditionIndex(IfStatement ifStatement) {
         return -1;
     }
 
+    /**
+     * Gets a protocol definition by name.
+     */
+    public Optional<ProtocolDefinition> getProtocolDefinition(String name) {
+        return protocolDefinitions.stream()
+                .filter(p -> p.name().equals(name))
+                .findFirst();
+    }
+
     /**
      * Gets a struct definition by name.
      */
@@ -181,6 +225,15 @@ public Optional<StructDefinition> getStructDefinition(String name) {
                 .findFirst();
     }
 
+    /**
+     * Gets a macro definition by name.
+     */
+    public Optional<MacroDefinition> getMacroDefinition(String name) {
+        return macroDefinitions.stream()
+                .filter(m -> m.name().equals(name))
+                .findFirst();
+    }
+
     /**
      * Gets a struct instance by variable name.
      */
@@ -196,9 +249,21 @@ public String toString() {
 
         var rtn = new StringBuilder();
         rtn.append("NAME \"").append(name).append("\"\n");
+        for (ImportStatement importStmt : imports) {
+            rtn.append(importStmt).append("\n");
+        }
+        for (LibraryStatement libraryStmt : libraries) {
+            rtn.append(libraryStmt).append("\n");
+        }
+        for (ProtocolDefinition protocolDef : protocolDefinitions) {
+            rtn.append(protocolDef).append("\n");
+        }
         for (StructDefinition structDef : structDefinitions) {
             rtn.append(structDef).append("\n");
         }
+        for (MacroDefinition macroDef : macroDefinitions) {
+            rtn.append(macroDef).append("\n");
+        }
         for (LetStatement letStmt : letStatements) {
             rtn.append(letStmt).append("\n");
         }
diff --git a/src/main/java/ca/teamdman/sfml/ast/ProtocolDefinition.java b/src/main/java/ca/teamdman/sfml/ast/ProtocolDefinition.java
new file mode 100644
index 000000000..bfd8c712e
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/ProtocolDefinition.java
@@ -0,0 +1,39 @@
+package ca.teamdman.sfml.ast;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * Represents a protocol definition in the program.
+ * Example:
+ * protocol Smeltable
+ *     input: sidequalifier slotqualifier
+ *     fuel: sidequalifier slotqualifier
+ *     output: sidequalifier slotqualifier
+ * end
+ */
+public record ProtocolDefinition(
+        String name,
+        List<ProtocolField> fields
+) implements ASTNode {
+
+    /**
+     * Gets a field by name from this protocol definition.
+     */
+    public Optional<ProtocolField> getField(String fieldName) {
+        return fields.stream()
+                .filter(f -> f.name().equals(fieldName))
+                .findFirst();
+    }
+
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder();
+        sb.append("protocol ").append(name).append("\n");
+        for (ProtocolField field : fields) {
+            sb.append("    ").append(field).append("\n");
+        }
+        sb.append("end");
+        return sb.toString();
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/ProtocolField.java b/src/main/java/ca/teamdman/sfml/ast/ProtocolField.java
new file mode 100644
index 000000000..ba8443292
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/ProtocolField.java
@@ -0,0 +1,16 @@
+package ca.teamdman.sfml.ast;
+
+/**
+ * Represents a field in a protocol definition.
+ * Example: input: sidequalifier slotqualifier
+ */
+public record ProtocolField(
+        String name,
+        ProtocolFieldType type
+) implements ASTNode {
+
+    @Override
+    public String toString() {
+        return name + ": " + type;
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/ProtocolFieldType.java b/src/main/java/ca/teamdman/sfml/ast/ProtocolFieldType.java
new file mode 100644
index 000000000..5595abac1
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/ast/ProtocolFieldType.java
@@ -0,0 +1,39 @@
+package ca.teamdman.sfml.ast;
+
+/**
+ * Represents the type of a field in a protocol definition.
+ */
+public enum ProtocolFieldType implements ASTNode {
+    SIDE_QUALIFIER,
+    SLOT_QUALIFIER,
+    SIDE_AND_SLOT,
+    LABEL,
+    RESOURCE,
+    NUMBER;
+
+    /**
+     * Checks if a struct field value matches this protocol field type.
+     */
+    public boolean matches(StructFieldValue value) {
+        return switch (this) {
+            case SIDE_QUALIFIER -> value instanceof SideQualifier;
+            case SLOT_QUALIFIER -> value instanceof NumberRangeSet;
+            case SIDE_AND_SLOT -> value instanceof CompositeFieldValue;
+            case LABEL -> value instanceof Label;
+            case RESOURCE -> value instanceof ResourceIdSet;
+            case NUMBER -> value instanceof Number;
+        };
+    }
+
+    @Override
+    public String toString() {
+        return switch (this) {
+            case SIDE_QUALIFIER -> "sidequalifier";
+            case SLOT_QUALIFIER -> "slotqualifier";
+            case SIDE_AND_SLOT -> "sidequalifier slotqualifier";
+            case LABEL -> "label";
+            case RESOURCE -> "resource";
+            case NUMBER -> "number";
+        };
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/ast/StructDefinition.java b/src/main/java/ca/teamdman/sfml/ast/StructDefinition.java
index 628c507b2..fa99be3b7 100644
--- a/src/main/java/ca/teamdman/sfml/ast/StructDefinition.java
+++ b/src/main/java/ca/teamdman/sfml/ast/StructDefinition.java
@@ -6,7 +6,7 @@
 /**
  * Represents a struct definition in the program.
  * Example:
- * struct Furnace
+ * struct Furnace : Smeltable
  *     input: TOP SIDE SLOTS 0
  *     fuel: BOTTOM SIDE SLOTS 1
  *     output: BOTTOM SIDE SLOTS 2
@@ -14,9 +14,17 @@
  */
 public record StructDefinition(
         String name,
+        List<String> implementedProtocols,
         List<StructField> fields
 ) implements ASTNode {
 
+    /**
+     * Constructs a StructDefinition without protocols for backwards compatibility.
+     */
+    public StructDefinition(String name, List<StructField> fields) {
+        this(name, List.of(), fields);
+    }
+
     /**
      * Gets a field by name from this struct definition.
      */
@@ -26,10 +34,21 @@ public Optional<StructField> getField(String fieldName) {
                 .findFirst();
     }
 
+    /**
+     * Checks if this struct implements the given protocol.
+     */
+    public boolean implementsProtocol(String protocolName) {
+        return implementedProtocols.contains(protocolName);
+    }
+
     @Override
     public String toString() {
         StringBuilder sb = new StringBuilder();
-        sb.append("struct ").append(name).append("\n");
+        sb.append("struct ").append(name);
+        if (!implementedProtocols.isEmpty()) {
+            sb.append(" : ").append(String.join(", ", implementedProtocols));
+        }
+        sb.append("\n");
         for (StructField field : fields) {
             sb.append("    ").append(field).append("\n");
         }
diff --git a/src/main/java/ca/teamdman/sfml/program_builder/ImportResolver.java b/src/main/java/ca/teamdman/sfml/program_builder/ImportResolver.java
new file mode 100644
index 000000000..eba2957e1
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/program_builder/ImportResolver.java
@@ -0,0 +1,24 @@
+package ca.teamdman.sfml.program_builder;
+
+import java.util.Optional;
+
+/**
+ * Interface for resolving file imports in SFML programs.
+ * Implementations can resolve imports from the filesystem, resources, or other sources.
+ */
+@FunctionalInterface
+public interface ImportResolver {
+
+    /**
+     * Resolves an import path to its SFML source code.
+     *
+     * @param path the import path (e.g., "machines.sfml")
+     * @return the SFML source code, or empty if not found
+     */
+    Optional<String> resolve(String path);
+
+    /**
+     * A resolver that always fails to find imports.
+     */
+    ImportResolver NONE = path -> Optional.empty();
+}
diff --git a/src/main/java/ca/teamdman/sfml/program_builder/LibraryDefinitions.java b/src/main/java/ca/teamdman/sfml/program_builder/LibraryDefinitions.java
new file mode 100644
index 000000000..95085b0d9
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/program_builder/LibraryDefinitions.java
@@ -0,0 +1,42 @@
+package ca.teamdman.sfml.program_builder;
+
+import ca.teamdman.sfml.ast.MacroDefinition;
+import ca.teamdman.sfml.ast.ProtocolDefinition;
+import ca.teamdman.sfml.ast.StructDefinition;
+
+import java.util.List;
+
+/**
+ * Contains definitions that can be shared via library blocks.
+ */
+public record LibraryDefinitions(
+        List<ProtocolDefinition> protocols,
+        List<StructDefinition> structs,
+        List<MacroDefinition> macros
+) {
+
+    public static final LibraryDefinitions EMPTY = new LibraryDefinitions(
+            List.of(),
+            List.of(),
+            List.of()
+    );
+
+    /**
+     * Merges this with another LibraryDefinitions, combining all definitions.
+     */
+    public LibraryDefinitions merge(LibraryDefinitions other) {
+        return new LibraryDefinitions(
+                concat(protocols, other.protocols),
+                concat(structs, other.structs),
+                concat(macros, other.macros)
+        );
+    }
+
+    private static <T> List<T> concat(List<T> a, List<T> b) {
+        if (a.isEmpty()) return b;
+        if (b.isEmpty()) return a;
+        var result = new java.util.ArrayList<>(a);
+        result.addAll(b);
+        return List.copyOf(result);
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfml/program_builder/LibraryResolver.java b/src/main/java/ca/teamdman/sfml/program_builder/LibraryResolver.java
new file mode 100644
index 000000000..3f5a534da
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfml/program_builder/LibraryResolver.java
@@ -0,0 +1,24 @@
+package ca.teamdman.sfml.program_builder;
+
+import java.util.Optional;
+
+/**
+ * Interface for resolving library block references in SFML programs.
+ * Implementations look up library blocks by their label in the cable network.
+ */
+@FunctionalInterface
+public interface LibraryResolver {
+
+    /**
+     * Resolves a library block by its label.
+     *
+     * @param blockLabel the label of the library block (e.g., "factory_config")
+     * @return the library definitions from the block, or empty if not found
+     */
+    Optional<LibraryDefinitions> resolve(String blockLabel);
+
+    /**
+     * A resolver that always fails to find libraries.
+     */
+    LibraryResolver NONE = label -> Optional.empty();
+}

From d2372c655ce10440e7e09bee6d49f87a5dd7ee43 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sat, 24 Jan 2026 20:29:11 +0100
Subject: [PATCH 09/33] feat: add library block for sharing SFML definitions

---
 .../sfm/common/block/LibraryBlock.java        |  70 +++++++++
 .../blockentity/LibraryBlockEntity.java       | 135 ++++++++++++++++++
 .../sfm/common/registry/SFMBlockEntities.java |  15 ++
 .../sfm/common/registry/SFMBlocks.java        |   9 ++
 .../sfm/common/registry/SFMItems.java         |   4 +
 5 files changed, 233 insertions(+)
 create mode 100644 src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java
 create mode 100644 src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java

diff --git a/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java b/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java
new file mode 100644
index 000000000..ed870cb4a
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java
@@ -0,0 +1,70 @@
+package ca.teamdman.sfm.common.block;
+
+import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
+import ca.teamdman.sfm.common.cablenetwork.CableNetworkManager;
+import ca.teamdman.sfm.common.cablenetwork.ICableBlock;
+import ca.teamdman.sfm.common.registry.SFMBlockEntities;
+import net.minecraft.core.BlockPos;
+import net.minecraft.world.level.Level;
+import net.minecraft.world.level.block.BaseEntityBlock;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.EntityBlock;
+import net.minecraft.world.level.block.RenderShape;
+import net.minecraft.world.level.block.SoundType;
+import net.minecraft.world.level.block.entity.BlockEntity;
+import net.minecraft.world.level.block.state.BlockBehaviour;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.material.Material;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * A block that stores SFML library definitions (protocols, structs, macros).
+ * Can be referenced by manager programs via "use library" statements.
+ */
+public class LibraryBlock extends BaseEntityBlock implements EntityBlock, ICableBlock {
+
+    public LibraryBlock() {
+        super(BlockBehaviour.Properties
+                .of(Material.PISTON)
+                .destroyTime(1.5f)
+                .sound(SoundType.METAL));
+    }
+
+    @Override
+    @SuppressWarnings("deprecation")
+    public RenderShape getRenderShape(BlockState state) {
+        return RenderShape.MODEL;
+    }
+
+    @Override
+    public @Nullable BlockEntity newBlockEntity(BlockPos pos, BlockState state) {
+        return SFMBlockEntities.LIBRARY_BLOCK_ENTITY.get().create(pos, state);
+    }
+
+    @Override
+    @SuppressWarnings("deprecation")
+    public void onPlace(
+            BlockState state,
+            Level world,
+            BlockPos pos,
+            BlockState oldState,
+            boolean isMoving
+    ) {
+        CableNetworkManager.onCablePlaced(world, pos);
+    }
+
+    @Override
+    @SuppressWarnings("deprecation")
+    public void onRemove(
+            BlockState state,
+            Level level,
+            BlockPos pos,
+            BlockState newState,
+            boolean isMoving
+    ) {
+        if (!state.is(newState.getBlock())) {
+            CableNetworkManager.onCableRemoved(level, pos);
+            super.onRemove(state, level, pos, newState, isMoving);
+        }
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
new file mode 100644
index 000000000..eeae5e1a2
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
@@ -0,0 +1,135 @@
+package ca.teamdman.sfm.common.blockentity;
+
+import ca.teamdman.sfm.common.registry.SFMBlockEntities;
+import ca.teamdman.sfml.program_builder.LibraryDefinitions;
+import net.minecraft.core.BlockPos;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.nbt.ListTag;
+import net.minecraft.nbt.StringTag;
+import net.minecraft.nbt.Tag;
+import net.minecraft.network.chat.Component;
+import net.minecraft.world.MenuProvider;
+import net.minecraft.world.entity.player.Inventory;
+import net.minecraft.world.entity.player.Player;
+import net.minecraft.world.inventory.AbstractContainerMenu;
+import net.minecraft.world.level.block.entity.BlockEntity;
+import net.minecraft.world.level.block.state.BlockState;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Block entity for library blocks that store SFML definitions (protocols, structs, macros).
+ * Library blocks can be referenced by manager programs to share common definitions.
+ */
+public class LibraryBlockEntity extends BlockEntity implements MenuProvider {
+
+    private static final String NBT_KEY_SOURCE = "Source";
+
+    /**
+     * The raw SFML source code containing the library definitions.
+     */
+    private String sourceCode = "";
+
+    /**
+     * Cached parsed definitions. Null if not yet parsed or if source is invalid.
+     */
+    @Nullable
+    private LibraryDefinitions cachedDefinitions = null;
+
+    /**
+     * Compilation errors, empty if compilation succeeded.
+     */
+    private List<String> compilationErrors = new ArrayList<>();
+
+    public LibraryBlockEntity(BlockPos pos, BlockState state) {
+        super(SFMBlockEntities.LIBRARY_BLOCK_ENTITY.get(), pos, state);
+    }
+
+    public String getSourceCode() {
+        return sourceCode;
+    }
+
+    public void setSourceCode(String sourceCode) {
+        this.sourceCode = sourceCode;
+        this.cachedDefinitions = null;
+        this.compilationErrors.clear();
+        setChanged();
+        recompile();
+    }
+
+    public List<String> getCompilationErrors() {
+        return compilationErrors;
+    }
+
+    public boolean hasErrors() {
+        return !compilationErrors.isEmpty();
+    }
+
+    /**
+     * Gets the library definitions, recompiling if necessary.
+     */
+    public LibraryDefinitions getDefinitions() {
+        if (cachedDefinitions == null) {
+            recompile();
+        }
+        return cachedDefinitions != null ? cachedDefinitions : LibraryDefinitions.EMPTY;
+    }
+
+    /**
+     * Recompiles the source code to extract definitions.
+     */
+    private void recompile() {
+        compilationErrors.clear();
+
+        if (sourceCode.isEmpty()) {
+            cachedDefinitions = LibraryDefinitions.EMPTY;
+            return;
+        }
+
+        try {
+            // Parse the source code as a library (only protocols, structs, macros)
+            // For now, we'll use a simplified approach - full parsing would need ASTBuilder
+            // This is a placeholder implementation
+            cachedDefinitions = parseLibraryDefinitions(sourceCode);
+        } catch (Exception e) {
+            compilationErrors.add(e.getMessage());
+            cachedDefinitions = null;
+        }
+    }
+
+    /**
+     * Parses library definitions from source code.
+     * TODO: Implement actual parsing using ASTBuilder to extract protocols, structs, and macros.
+     * This requires refactoring ASTBuilder to support partial program parsing.
+     */
+    private LibraryDefinitions parseLibraryDefinitions(String source) {
+        // Stub implementation - library block parsing not yet implemented
+        return LibraryDefinitions.EMPTY;
+    }
+
+    @Override
+    protected void saveAdditional(CompoundTag tag) {
+        super.saveAdditional(tag);
+        tag.putString(NBT_KEY_SOURCE, sourceCode);
+    }
+
+    @Override
+    public void load(CompoundTag tag) {
+        super.load(tag);
+        sourceCode = tag.getString(NBT_KEY_SOURCE);
+        cachedDefinitions = null;
+    }
+
+    @Override
+    public Component getDisplayName() {
+        return Component.translatable("container.sfm.library");
+    }
+
+    @Override
+    public @Nullable AbstractContainerMenu createMenu(int containerId, Inventory playerInventory, Player player) {
+        // Library blocks don't have a GUI menu yet - could be added later for editing
+        return null;
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfm/common/registry/SFMBlockEntities.java b/src/main/java/ca/teamdman/sfm/common/registry/SFMBlockEntities.java
index ebda500fe..4c376cc3f 100644
--- a/src/main/java/ca/teamdman/sfm/common/registry/SFMBlockEntities.java
+++ b/src/main/java/ca/teamdman/sfm/common/registry/SFMBlockEntities.java
@@ -3,6 +3,7 @@
 
 import ca.teamdman.sfm.SFM;
 import ca.teamdman.sfm.common.blockentity.*;
+import ca.teamdman.sfm.common.util.SFMEnvironmentUtils;
 import net.minecraft.world.level.block.entity.BlockEntityType;
 import net.minecraftforge.eventbus.api.IEventBus;
 
@@ -92,4 +93,18 @@ public static void register(IEventBus bus) {
                     .build(null)
     );
 
+    public static SFMRegistryObject<BlockEntityType<?>, BlockEntityType<LibraryBlockEntity>>
+            LIBRARY_BLOCK_ENTITY = null;
+
+    static {
+        if (SFMEnvironmentUtils.isInIDE() && SFMBlocks.LIBRARY_BLOCK != null) {
+            LIBRARY_BLOCK_ENTITY = REGISTERER.register(
+                    "library",
+                    () -> BlockEntityType.Builder
+                            .of(LibraryBlockEntity::new, SFMBlocks.LIBRARY_BLOCK.get())
+                            .build(null)
+            );
+        }
+    }
+
 }
diff --git a/src/main/java/ca/teamdman/sfm/common/registry/SFMBlocks.java b/src/main/java/ca/teamdman/sfm/common/registry/SFMBlocks.java
index 4d2a09aff..23c63fcc2 100644
--- a/src/main/java/ca/teamdman/sfm/common/registry/SFMBlocks.java
+++ b/src/main/java/ca/teamdman/sfm/common/registry/SFMBlocks.java
@@ -2,6 +2,7 @@
 
 import ca.teamdman.sfm.SFM;
 import ca.teamdman.sfm.common.block.*;
+import ca.teamdman.sfm.common.util.SFMEnvironmentUtils;
 import net.minecraft.world.level.block.Block;
 import net.minecraft.world.level.block.SoundType;
 import net.minecraft.world.level.block.state.BlockBehaviour;
@@ -97,6 +98,14 @@ public class SFMBlocks {
                     )
             );
 
+    public static SFMRegistryObject<Block, LibraryBlock> LIBRARY_BLOCK = null;
+
+    static {
+        if (SFMEnvironmentUtils.isInIDE()) {
+            LIBRARY_BLOCK = REGISTERER.register("library", LibraryBlock::new);
+        }
+    }
+
     public static void register(IEventBus bus) {
 
         REGISTERER.register(bus);
diff --git a/src/main/java/ca/teamdman/sfm/common/registry/SFMItems.java b/src/main/java/ca/teamdman/sfm/common/registry/SFMItems.java
index ccf88c99c..ee9a88c41 100644
--- a/src/main/java/ca/teamdman/sfm/common/registry/SFMItems.java
+++ b/src/main/java/ca/teamdman/sfm/common/registry/SFMItems.java
@@ -79,10 +79,14 @@ public class SFMItems {
     );
 
     public static SFMRegistryObject<Item, BlockItem> BUFFER_ITEM = null;
+    public static SFMRegistryObject<Item, BlockItem> LIBRARY_ITEM = null;
 
     static {
         if (SFMEnvironmentUtils.isInIDE()) {
             BUFFER_ITEM = register("buffer", SFMBlocks.BUFFER_BLOCK);
+            if (SFMBlocks.LIBRARY_BLOCK != null) {
+                LIBRARY_ITEM = register("library", SFMBlocks.LIBRARY_BLOCK);
+            }
         }
     }
 

From 6274bb6b5e361bc4433cce32ed8ad200efe28c7b Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sat, 24 Jan 2026 20:29:28 +0100
Subject: [PATCH 10/33] feat: add linters for protocol and macro usage

---
 .../program/linting/MacroUsageLinter.java     | 74 +++++++++++++++++++
 .../program/linting/ProtocolUsageLinter.java  | 70 ++++++++++++++++++
 .../common/registry/SFMProgramLinters.java    | 12 +++
 3 files changed, 156 insertions(+)
 create mode 100644 src/main/java/ca/teamdman/sfm/common/program/linting/MacroUsageLinter.java
 create mode 100644 src/main/java/ca/teamdman/sfm/common/program/linting/ProtocolUsageLinter.java

diff --git a/src/main/java/ca/teamdman/sfm/common/program/linting/MacroUsageLinter.java b/src/main/java/ca/teamdman/sfm/common/program/linting/MacroUsageLinter.java
new file mode 100644
index 000000000..57f840027
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfm/common/program/linting/MacroUsageLinter.java
@@ -0,0 +1,74 @@
+package ca.teamdman.sfm.common.program.linting;
+
+import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
+import ca.teamdman.sfm.common.label.LabelPositionHolder;
+import ca.teamdman.sfml.ast.ExpandStatement;
+import ca.teamdman.sfml.ast.MacroDefinition;
+import ca.teamdman.sfml.ast.Program;
+import ca.teamdman.sfml.ast.Statement;
+import ca.teamdman.sfml.ast.Trigger;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.Level;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.ArrayDeque;
+import java.util.Deque;
+import java.util.HashSet;
+import java.util.Set;
+
+import static ca.teamdman.sfm.common.localization.LocalizationKeys.PROGRAM_WARNING_UNUSED_MACRO;
+
+/**
+ * Linter that validates macro usage.
+ * Warns if a macro is defined but never expanded.
+ */
+public class MacroUsageLinter implements IProgramLinter {
+    @Override
+    public void gatherWarnings(
+            Program program,
+            LabelPositionHolder labelPositionHolder,
+            @Nullable ManagerBlockEntity managerBlockEntity,
+            ProblemTracker tracker
+    ) {
+        // Collect all macro names that are used in expand statements
+        Set<String> usedMacros = new HashSet<>();
+        collectUsedMacros(program, usedMacros);
+
+        // Check for unused macro definitions
+        for (MacroDefinition macroDef : program.macroDefinitions()) {
+            if (!usedMacros.contains(macroDef.name())) {
+                if (tracker.add(PROGRAM_WARNING_UNUSED_MACRO.get(macroDef.name())).isSaturated()) {
+                    return;
+                }
+            }
+        }
+    }
+
+    private void collectUsedMacros(Program program, Set<String> usedMacros) {
+        Deque<Statement> toVisit = new ArrayDeque<>();
+        for (Trigger trigger : program.triggers()) {
+            toVisit.addAll(trigger.getStatements());
+        }
+
+        while (!toVisit.isEmpty()) {
+            Statement stmt = toVisit.poll();
+
+            if (stmt instanceof ExpandStatement expand) {
+                usedMacros.add(expand.macroName());
+            }
+
+            toVisit.addAll(stmt.getStatements());
+        }
+    }
+
+    @Override
+    public void fixWarnings(
+            Program program,
+            LabelPositionHolder labels,
+            ManagerBlockEntity manager,
+            Level level,
+            ItemStack disk
+    ) {
+        // Cannot auto-fix - removing unused macros would require modifying source code
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfm/common/program/linting/ProtocolUsageLinter.java b/src/main/java/ca/teamdman/sfm/common/program/linting/ProtocolUsageLinter.java
new file mode 100644
index 000000000..c72f14b51
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfm/common/program/linting/ProtocolUsageLinter.java
@@ -0,0 +1,70 @@
+package ca.teamdman.sfm.common.program.linting;
+
+import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
+import ca.teamdman.sfm.common.label.LabelPositionHolder;
+import ca.teamdman.sfml.ast.MacroDefinition;
+import ca.teamdman.sfml.ast.MacroParameter;
+import ca.teamdman.sfml.ast.Program;
+import ca.teamdman.sfml.ast.ProtocolDefinition;
+import ca.teamdman.sfml.ast.StructDefinition;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.Level;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import static ca.teamdman.sfm.common.localization.LocalizationKeys.PROGRAM_WARNING_UNUSED_PROTOCOL;
+
+/**
+ * Linter that warns about protocols that are defined but never used.
+ * A protocol is "used" if:
+ * - A struct implements it
+ * - A macro parameter is constrained by it
+ */
+public class ProtocolUsageLinter implements IProgramLinter {
+    @Override
+    public void gatherWarnings(
+            Program program,
+            LabelPositionHolder labelPositionHolder,
+            @Nullable ManagerBlockEntity managerBlockEntity,
+            ProblemTracker tracker
+    ) {
+        // Collect all protocols that are referenced
+        Set<String> usedProtocols = new HashSet<>();
+
+        // Protocols implemented by structs
+        for (StructDefinition structDef : program.structDefinitions()) {
+            usedProtocols.addAll(structDef.implementedProtocols());
+        }
+
+        // Protocols used as macro parameter constraints
+        for (MacroDefinition macroDef : program.macroDefinitions()) {
+            for (MacroParameter param : macroDef.parameters()) {
+                if (param.protocolConstraint() != null) {
+                    usedProtocols.add(param.protocolConstraint());
+                }
+            }
+        }
+
+        // Check for unused protocol definitions
+        for (ProtocolDefinition protocolDef : program.protocolDefinitions()) {
+            if (!usedProtocols.contains(protocolDef.name())) {
+                if (tracker.add(PROGRAM_WARNING_UNUSED_PROTOCOL.get(protocolDef.name())).isSaturated()) {
+                    return;
+                }
+            }
+        }
+    }
+
+    @Override
+    public void fixWarnings(
+            Program program,
+            LabelPositionHolder labels,
+            ManagerBlockEntity manager,
+            Level level,
+            ItemStack disk
+    ) {
+        // Cannot auto-fix - removing unused protocols would require modifying source code
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfm/common/registry/SFMProgramLinters.java b/src/main/java/ca/teamdman/sfm/common/registry/SFMProgramLinters.java
index 84f21bdb8..6f3ff7105 100644
--- a/src/main/java/ca/teamdman/sfm/common/registry/SFMProgramLinters.java
+++ b/src/main/java/ca/teamdman/sfm/common/registry/SFMProgramLinters.java
@@ -81,6 +81,18 @@ public class SFMProgramLinters {
             StructUsageLinter::new
     );
 
+    public static final SFMRegistryObject<IProgramLinter, ProtocolUsageLinter>
+            PROTOCOL_USAGE_LINTER = REGISTERER.register(
+            "protocol_usage",
+            ProtocolUsageLinter::new
+    );
+
+    public static final SFMRegistryObject<IProgramLinter, MacroUsageLinter>
+            MACRO_USAGE_LINTER = REGISTERER.register(
+            "macro_usage",
+            MacroUsageLinter::new
+    );
+
     static {
         if (SFMModCompat.isMekanismLoaded()) {
             SFMMekanismCompat.registerProgramLinters(REGISTERER);

From b6705d9e77686bee0f87e70f1e550e54b156771c Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sat, 24 Jan 2026 20:29:38 +0100
Subject: [PATCH 11/33] feat: add syntax highlighting and localization for new
 keywords

---
 .../ProgramSyntaxHighlightingHelper.java        | 16 ++++++++++++++++
 .../common/localization/LocalizationKeys.java   | 17 +++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/src/main/java/ca/teamdman/sfm/client/text_styling/ProgramSyntaxHighlightingHelper.java b/src/main/java/ca/teamdman/sfm/client/text_styling/ProgramSyntaxHighlightingHelper.java
index 599794f14..7f026fed7 100644
--- a/src/main/java/ca/teamdman/sfm/client/text_styling/ProgramSyntaxHighlightingHelper.java
+++ b/src/main/java/ca/teamdman/sfm/client/text_styling/ProgramSyntaxHighlightingHelper.java
@@ -156,6 +156,22 @@ private static ChatFormatting getColour(Token token) {
             case SFMLLexer.BLOCK:
             case SFMLLexer.LABEL:
                 return ChatFormatting.YELLOW;
+            // Protocol, macro, and library keywords
+            case SFMLLexer.PROTOCOL:
+            case SFMLLexer.STRUCT:
+            case SFMLLexer.LET:
+            case SFMLLexer.USING:
+            case SFMLLexer.MACRO:
+            case SFMLLexer.EXPAND:
+            case SFMLLexer.IMPORT:
+            case SFMLLexer.USE:
+            case SFMLLexer.LIBRARY:
+                return ChatFormatting.BLUE;
+            case SFMLLexer.SIDEQUALIFIER:
+            case SFMLLexer.SLOTQUALIFIER:
+            case SFMLLexer.RESOURCE:
+            case SFMLLexer.NUMBERTYPE:
+                return ChatFormatting.DARK_PURPLE;
             default:
                 return ChatFormatting.WHITE;
         }
diff --git a/src/main/java/ca/teamdman/sfm/common/localization/LocalizationKeys.java b/src/main/java/ca/teamdman/sfm/common/localization/LocalizationKeys.java
index 386ff73e8..97ce78be9 100644
--- a/src/main/java/ca/teamdman/sfm/common/localization/LocalizationKeys.java
+++ b/src/main/java/ca/teamdman/sfm/common/localization/LocalizationKeys.java
@@ -484,6 +484,23 @@ public final class LocalizationKeys {
             "program.sfm.warnings.unused_struct_instance",
             "Struct instance \"%s\" is defined but never used in a USING clause."
     );
+    public static final LocalizationEntry PROGRAM_WARNING_UNUSED_PROTOCOL = new LocalizationEntry(
+            "program.sfm.warnings.unused_protocol",
+            "Protocol \"%s\" is defined but never used."
+    );
+    public static final LocalizationEntry PROGRAM_WARNING_UNUSED_MACRO = new LocalizationEntry(
+            "program.sfm.warnings.unused_macro",
+            "Macro \"%s\" is defined but never expanded."
+    );
+    public static final LocalizationEntry LIBRARY_CONTAINER = new LocalizationEntry(
+            "container.sfm.library",
+            "SFML Library"
+    );
+    @SuppressWarnings("unused") // used by minecraft without us having to directly reference
+    public static final LocalizationEntry LIBRARY_BLOCK = new LocalizationEntry(
+            "block.sfm.library",
+            "SFML Library Block"
+    );
     public static final LocalizationEntry PROGRAM_ERROR_COMPILE_FAILED = new LocalizationEntry(
             "program.sfm.error.compile_failed",
             "Failed to compile."

From 5eebc389a3483292365b8923701a3ba195e14c73 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sat, 24 Jan 2026 20:29:50 +0100
Subject: [PATCH 12/33] test: add tests for protocols, macros, and structs

---
 .../sfm/gametest/SFMGameTestHelper.java       |   2 +-
 .../SFMDeclarativeTestBuilder.java            |   2 +-
 .../struct/MacroBasicExpansionGameTest.java   |  49 ++
 .../struct/MacroWithStructAccessGameTest.java |  62 +++
 .../gametest/tests/struct/package-info.java   |  10 +
 src/test/java/ca/teamdman/sfml/SFMLTests.java | 502 ++++++++++++++++++
 6 files changed, 625 insertions(+), 2 deletions(-)
 create mode 100644 src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroBasicExpansionGameTest.java
 create mode 100644 src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroWithStructAccessGameTest.java
 create mode 100644 src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/package-info.java

diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/SFMGameTestHelper.java b/src/gametest/java/ca/teamdman/sfm/gametest/SFMGameTestHelper.java
index 7d7090afe..23ef59476 100644
--- a/src/gametest/java/ca/teamdman/sfm/gametest/SFMGameTestHelper.java
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/SFMGameTestHelper.java
@@ -178,7 +178,7 @@ public void assertExpr(
 
         BoolExpr expr = BoolExpr.from(exprString);
         ProgramContext programContext = new ProgramContext(
-                new Program(new ASTBuilder(), "temp lol", List.of(), Set.of(), Set.of()),
+                new Program(new ASTBuilder(), "temp lol", List.of(), List.of(), List.of(), Set.of(), Set.of()),
                 manager,
                 ExecuteProgramBehaviour::new
         );
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/declarative/SFMDeclarativeTestBuilder.java b/src/gametest/java/ca/teamdman/sfm/gametest/declarative/SFMDeclarativeTestBuilder.java
index 0117d1bc3..9f7d3caf8 100644
--- a/src/gametest/java/ca/teamdman/sfm/gametest/declarative/SFMDeclarativeTestBuilder.java
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/declarative/SFMDeclarativeTestBuilder.java
@@ -112,7 +112,7 @@ private void runConditions(
         if (conditions.isEmpty()) return;
         List<BoolExpr> expressions = conditions.stream().map(BoolExpr::from).toList();
         ProgramContext programContext = new ProgramContext(
-                new Program(new ASTBuilder(), "temp lol", List.of(), Set.of(), Set.of()),
+                new Program(new ASTBuilder(), "temp lol", List.of(), List.of(), List.of(), Set.of(), Set.of()),
                 manager,
                 ExecuteProgramBehaviour::new
         );
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroBasicExpansionGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroBasicExpansionGameTest.java
new file mode 100644
index 000000000..881e3bad7
--- /dev/null
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroBasicExpansionGameTest.java
@@ -0,0 +1,49 @@
+package ca.teamdman.sfm.gametest.tests.struct;
+
+import ca.teamdman.sfm.gametest.LeftRightManagerTest;
+import ca.teamdman.sfm.gametest.SFMGameTest;
+import ca.teamdman.sfm.gametest.SFMGameTestDefinition;
+import ca.teamdman.sfm.gametest.SFMGameTestHelper;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.block.Blocks;
+
+import java.util.Arrays;
+import java.util.Collections;
+
+/**
+ * Tests that macro expansion works at runtime.
+ * The macro transfers items from 'left' to 'right' using the expand statement.
+ */
+@SuppressWarnings("ArraysAsListWithZeroOrOneArgument")
+@SFMGameTest
+public class MacroBasicExpansionGameTest extends SFMGameTestDefinition {
+    @Override
+    public String template() {
+        return "3x2x1";
+    }
+
+    @Override
+    public void run(SFMGameTestHelper helper) {
+        var test = new LeftRightManagerTest(helper);
+        test.setProgram("""
+                NAME "Macro Basic Expansion Test"
+
+                macro transfer(source, dest)
+                    input from source
+                    output to dest
+                end
+
+                every 20 ticks do
+                    expand transfer(left, right)
+                end
+                """);
+        test.preContents("left", Arrays.asList(
+                new ItemStack(Blocks.DIRT, 64)
+        ));
+        test.postContents("left", Collections.emptyList());
+        test.postContents("right", Arrays.asList(
+                new ItemStack(Blocks.DIRT, 64)
+        ));
+        test.run();
+    }
+}
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroWithStructAccessGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroWithStructAccessGameTest.java
new file mode 100644
index 000000000..b81d7a519
--- /dev/null
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroWithStructAccessGameTest.java
@@ -0,0 +1,62 @@
+package ca.teamdman.sfm.gametest.tests.struct;
+
+import ca.teamdman.sfm.gametest.LeftRightManagerTest;
+import ca.teamdman.sfm.gametest.SFMGameTest;
+import ca.teamdman.sfm.gametest.SFMGameTestDefinition;
+import ca.teamdman.sfm.gametest.SFMGameTestHelper;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.block.Blocks;
+
+import java.util.Arrays;
+import java.util.Collections;
+
+/**
+ * Tests that macro expansion works with struct access using the USING keyword.
+ * This tests the "machine using field" syntax within macros.
+ */
+@SuppressWarnings("ArraysAsListWithZeroOrOneArgument")
+@SFMGameTest
+public class MacroWithStructAccessGameTest extends SFMGameTestDefinition {
+    @Override
+    public String template() {
+        return "3x2x1";
+    }
+
+    @Override
+    public void run(SFMGameTestHelper helper) {
+        var test = new LeftRightManagerTest(helper);
+        test.setProgram("""
+                NAME "Macro with Struct Access Test"
+
+                protocol Container
+                    main: sidequalifier slotqualifier
+                end
+
+                struct Chest : Container
+                    main: EACH SIDE SLOTS 0-26
+                end
+
+                macro process(machine: Container, source, dest)
+                    input from source
+                    output to machine using main
+                    forget
+                    input from machine using main
+                    output to dest
+                end
+
+                let storage = Chest { label: "left" }
+
+                every 20 ticks do
+                    expand process(storage, left, right)
+                end
+                """);
+        test.preContents("left", Arrays.asList(
+                new ItemStack(Blocks.DIRT, 64)
+        ));
+        test.postContents("left", Collections.emptyList());
+        test.postContents("right", Arrays.asList(
+                new ItemStack(Blocks.DIRT, 64)
+        ));
+        test.run();
+    }
+}
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/package-info.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/package-info.java
new file mode 100644
index 000000000..62183791a
--- /dev/null
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/package-info.java
@@ -0,0 +1,10 @@
+/**
+ * Game tests for struct and macro functionality.
+ * <p>
+ * Tests cover:
+ * <ul>
+ *   <li>Basic macro expansion with simple parameter passing</li>
+ *   <li>Macro expansion with struct protocol constraints and field access</li>
+ * </ul>
+ */
+package ca.teamdman.sfm.gametest.tests.struct;
diff --git a/src/test/java/ca/teamdman/sfml/SFMLTests.java b/src/test/java/ca/teamdman/sfml/SFMLTests.java
index 023538d0e..5fb76027f 100644
--- a/src/test/java/ca/teamdman/sfml/SFMLTests.java
+++ b/src/test/java/ca/teamdman/sfml/SFMLTests.java
@@ -1014,4 +1014,506 @@ public void structSlotOnlyField() {
                         """
         );
     }
+
+    // ===== PROTOCOL TESTS =====
+
+    @Test
+    public void protocolBasicDefinition() {
+        assertNoCompileErrors(
+                """
+                        NAME "Protocol Test"
+
+                        protocol Smeltable
+                            input: sidequalifier slotqualifier
+                            fuel: sidequalifier slotqualifier
+                            output: sidequalifier slotqualifier
+                        end
+
+                        struct Furnace : Smeltable
+                            input: TOP SIDE SLOTS 0
+                            fuel: BOTTOM SIDE SLOTS 1
+                            output: BOTTOM SIDE SLOTS 2
+                        end
+
+                        let smelter = Furnace { label: "furnaces" }
+
+                        every 20 ticks do
+                            input from chest
+                            output to smelter using input
+                        end
+                        """
+        );
+    }
+
+    @Test
+    public void protocolMultipleImplementation() {
+        assertNoCompileErrors(
+                """
+                        NAME "Multiple Protocol Test"
+
+                        protocol HasInput
+                            input: sidequalifier slotqualifier
+                        end
+
+                        protocol HasOutput
+                            output: sidequalifier slotqualifier
+                        end
+
+                        struct Machine : HasInput, HasOutput
+                            input: TOP SIDE SLOTS 0
+                            output: BOTTOM SIDE SLOTS 1
+                        end
+
+                        let machine = Machine { label: "machines" }
+
+                        every 20 ticks do
+                            input from chest
+                            output to machine using input
+                        end
+                        """
+        );
+    }
+
+    @Test
+    public void protocolUnknownProtocol() {
+        var input = """
+                NAME "Unknown Protocol Test"
+
+                struct Furnace : UnknownProtocol
+                    input: TOP SIDE SLOTS 0
+                end
+
+                let smelter = Furnace { label: "test" }
+
+                every 20 ticks do
+                    input from chest
+                end
+                """;
+        assertCompileErrorsPresent(input);
+    }
+
+    @Test
+    public void protocolMissingField() {
+        var input = """
+                NAME "Missing Protocol Field Test"
+
+                protocol Smeltable
+                    input: sidequalifier slotqualifier
+                    output: sidequalifier slotqualifier
+                end
+
+                struct Furnace : Smeltable
+                    input: TOP SIDE SLOTS 0
+                end
+
+                let smelter = Furnace { label: "test" }
+
+                every 20 ticks do
+                    input from chest
+                end
+                """;
+        assertCompileErrorsPresent(input);
+    }
+
+    @Test
+    public void protocolFieldTypeMismatch() {
+        var input = """
+                NAME "Protocol Field Type Mismatch Test"
+
+                protocol Smeltable
+                    input: sidequalifier slotqualifier
+                end
+
+                struct Furnace : Smeltable
+                    input: 42
+                end
+
+                let smelter = Furnace { label: "test" }
+
+                every 20 ticks do
+                    input from chest
+                end
+                """;
+        assertCompileErrorsPresent(input);
+    }
+
+    @Test
+    public void protocolDuplicateDefinition() {
+        var input = """
+                NAME "Duplicate Protocol Test"
+
+                protocol Smeltable
+                    input: sidequalifier
+                end
+
+                protocol Smeltable
+                    output: sidequalifier
+                end
+
+                every 20 ticks do
+                    input from chest
+                end
+                """;
+        assertCompileErrorsPresent(input);
+    }
+
+    // ===== MACRO TESTS =====
+
+    @Test
+    public void macroBasicDefinition() {
+        assertNoCompileErrors(
+                """
+                        NAME "Macro Test"
+
+                        macro transfer(source, dest)
+                            input from source
+                            output to dest
+                        end
+
+                        every 20 ticks do
+                            expand transfer(chest_a, chest_b)
+                        end
+                        """
+        );
+    }
+
+    @Test
+    public void macroWithProtocolConstraint() {
+        assertNoCompileErrors(
+                """
+                        NAME "Macro with Protocol Test"
+
+                        protocol Smeltable
+                            input: sidequalifier slotqualifier
+                            output: sidequalifier slotqualifier
+                        end
+
+                        struct Furnace : Smeltable
+                            input: TOP SIDE SLOTS 0
+                            output: BOTTOM SIDE SLOTS 1
+                        end
+
+                        macro smelt(machine: Smeltable, source, dest)
+                            input from source
+                            output to machine using input
+                            forget
+                            input from machine using output
+                            output to dest
+                        end
+
+                        let furnace = Furnace { label: "furnaces" }
+
+                        every 20 ticks do
+                            expand smelt(furnace, ore_chest, ingot_chest)
+                        end
+                        """
+        );
+    }
+
+    @Test
+    public void macroUnknownMacro() {
+        var input = """
+                NAME "Unknown Macro Test"
+
+                every 20 ticks do
+                    expand unknown_macro(chest_a, chest_b)
+                end
+                """;
+        assertCompileErrorsPresent(input);
+    }
+
+    @Test
+    public void macroWrongArgCount() {
+        var input = """
+                NAME "Wrong Arg Count Test"
+
+                macro transfer(source, dest)
+                    input from source
+                    output to dest
+                end
+
+                every 20 ticks do
+                    expand transfer(chest_a)
+                end
+                """;
+        assertCompileErrorsPresent(input);
+    }
+
+    @Test
+    public void macroProtocolConstraintNotMet() {
+        var input = """
+                NAME "Protocol Constraint Not Met Test"
+
+                protocol Smeltable
+                    input: sidequalifier slotqualifier
+                end
+
+                struct NonSmeltable
+                    other: TOP SIDE
+                end
+
+                macro smelt(machine: Smeltable)
+                    input from machine using input
+                end
+
+                let device = NonSmeltable { label: "devices" }
+
+                every 20 ticks do
+                    expand smelt(device)
+                end
+                """;
+        assertCompileErrorsPresent(input);
+    }
+
+    @Test
+    public void macroDuplicateDefinition() {
+        var input = """
+                NAME "Duplicate Macro Test"
+
+                macro transfer(a, b)
+                    input from a
+                end
+
+                macro transfer(x, y)
+                    output to x
+                end
+
+                every 20 ticks do
+                    expand transfer(chest_a, chest_b)
+                end
+                """;
+        assertCompileErrorsPresent(input);
+    }
+
+    @Test
+    public void macroWithForget() {
+        assertNoCompileErrors(
+                """
+                        NAME "Macro with Forget Test"
+
+                        macro process(source, dest)
+                            input from source
+                            output to dest
+                            forget
+                        end
+
+                        every 20 ticks do
+                            expand process(chest_a, chest_b)
+                            expand process(chest_c, chest_d)
+                        end
+                        """
+        );
+    }
+
+    @Test
+    public void macroWithResourceLimits() {
+        assertNoCompileErrors(
+                """
+                        NAME "Macro with Resource Limits Test"
+
+                        macro limited_transfer(source, dest)
+                            input 64 iron from source
+                            output 64 iron to dest
+                        end
+
+                        every 20 ticks do
+                            expand limited_transfer(chest_a, chest_b)
+                        end
+                        """
+        );
+    }
+
+    @Test
+    public void macroWithRetain() {
+        assertNoCompileErrors(
+                """
+                        NAME "Macro with Retain Test"
+
+                        protocol Smeltable
+                            input: sidequalifier slotqualifier
+                            fuel: sidequalifier slotqualifier
+                            output: sidequalifier slotqualifier
+                        end
+
+                        struct Furnace : Smeltable
+                            input: TOP SIDE SLOTS 0
+                            fuel: BOTTOM SIDE SLOTS 1
+                            output: BOTTOM SIDE SLOTS 0
+                        end
+
+                        macro smelt(machine: Smeltable, ore_source, fuel_source, dest)
+                            input from ore_source
+                            output retain 2 to each machine using input
+
+                            input from fuel_source
+                            output retain 2 to each machine using fuel
+
+                            forget
+
+                            input from machine using output
+                            output to dest
+                        end
+
+                        let furnace = Furnace { label: "furnaces" }
+
+                        every 20 ticks do
+                            expand smelt(furnace, ore_chest, fuel_chest, result_chest)
+                        end
+                        """
+        );
+    }
+
+    @Test
+    public void macroExpansionVerification() {
+        var input = """
+                NAME "Macro Expansion Verification Test"
+
+                macro transfer(source, dest)
+                    input from source
+                    output to dest
+                end
+
+                every 20 ticks do
+                    expand transfer(chest_a, chest_b)
+                end
+                """;
+        assertNoCompileErrors(input);
+        var program = compile(input);
+
+        // Verify structure
+        assertEquals(1, program.triggers().size());
+        var trigger = program.triggers().get(0);
+        var block = trigger.getBlock();
+        var statements = block.getStatements();
+
+        // Should have 1 expand statement
+        assertEquals(1, statements.size());
+        assertTrue(statements.get(0) instanceof ca.teamdman.sfml.ast.ExpandStatement);
+
+        // Verify the expand statement has 2 expanded statements (input + output)
+        var expandStmt = (ca.teamdman.sfml.ast.ExpandStatement) statements.get(0);
+        assertEquals(2, expandStmt.expandedStatements().size());
+        assertTrue(expandStmt.expandedStatements().get(0) instanceof ca.teamdman.sfml.ast.InputStatement);
+        assertTrue(expandStmt.expandedStatements().get(1) instanceof ca.teamdman.sfml.ast.OutputStatement);
+    }
+
+    // ===== IMPORT AND LIBRARY TESTS =====
+
+    @Test
+    public void importStatement() {
+        // Import statements parse correctly (resolution happens at build time)
+        assertNoCompileErrors(
+                """
+                        NAME "Import Test"
+
+                        import "machines.sfml"
+
+                        every 20 ticks do
+                            input from chest
+                        end
+                        """
+        );
+    }
+
+    @Test
+    public void libraryStatement() {
+        // Library statements parse correctly (resolution happens at build time)
+        assertNoCompileErrors(
+                """
+                        NAME "Library Test"
+
+                        use library "factory_config"
+
+                        every 20 ticks do
+                            input from chest
+                        end
+                        """
+        );
+    }
+
+    @Test
+    public void multipleImportsAndLibraries() {
+        assertNoCompileErrors(
+                """
+                        NAME "Multiple Imports Test"
+
+                        import "machines.sfml"
+                        import "protocols.sfml"
+                        use library "factory_config"
+                        use library "shared_macros"
+
+                        every 20 ticks do
+                            input from chest
+                        end
+                        """
+        );
+    }
+
+    // ===== COMBINED FEATURE TESTS =====
+
+    @Test
+    public void fullAutomationExample() {
+        assertNoCompileErrors(
+                """
+                        NAME "Full Automation"
+
+                        protocol Smeltable
+                            input: sidequalifier slotqualifier
+                            fuel: sidequalifier slotqualifier
+                            output: sidequalifier slotqualifier
+                        end
+
+                        struct Furnace : Smeltable
+                            input: TOP SIDE SLOTS 0
+                            fuel: BOTTOM SIDE SLOTS 1
+                            output: BOTTOM SIDE SLOTS 2
+                        end
+
+                        macro smelt(machine: Smeltable, source, dest)
+                            input from source
+                            output to machine using input
+                            forget
+                            input from machine using output
+                            output to dest
+                        end
+
+                        let furnace = Furnace { label: "furnaces" }
+
+                        every 20 ticks do
+                            expand smelt(furnace, ore_chest, ingot_chest)
+                        end
+                        """
+        );
+    }
+
+    @Test
+    public void protocolWithAllFieldTypes() {
+        assertNoCompileErrors(
+                """
+                        NAME "All Field Types Test"
+
+                        protocol AllTypes
+                            sides: sidequalifier
+                            slots: slotqualifier
+                            both: sidequalifier slotqualifier
+                            lbl: label
+                            num: number
+                        end
+
+                        struct Implementation : AllTypes
+                            sides: TOP, BOTTOM SIDE
+                            slots: SLOTS 0-5
+                            both: EACH SIDE SLOTS 0
+                            lbl: "my_label"
+                            num: 42
+                        end
+
+                        let impl = Implementation { label: "test" }
+
+                        every 20 ticks do
+                            input from chest
+                        end
+                        """
+        );
+    }
 }

From cb497053a9dcaf2630397c253cb8fc6ecbf63a07 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 00:59:12 +0100
Subject: [PATCH 13/33] feat: add library block GUI, textures, and disk
 indicator renderer

---
 .../SFMBlockStatesAndModelsDatagen.java       |  33 ++
 .../sfm/datagen/SFMItemModelsDatagen.java     |   3 +
 .../sfm/datagen/SFMLootTablesDatagen.java     |   3 +
 .../67cce32b1c3cbbcb1f646605f4914e3f196986c2  |   3 +-
 .../726a4eaaa226cb50028c5f3f85d691417b67903b  |   3 +-
 .../bf0ffec7956ce36aba0a993095f41e47d655813b  |   4 +-
 .../c622617f6fabf890a00b9275cd5f643584a8a2c8  |   4 +-
 .../assets/sfm/blockstates/library.json       |  19 +
 .../resources/assets/sfm/lang/en_us.json      |  10 +
 .../assets/sfm/models/block/library.json      |  12 +
 .../assets/sfm/models/item/library.json       |   3 +
 .../data/sfm/loot_tables/blocks/library.json  |  20 ++
 .../registry/SFMBlockEntityRenderers.java     |   7 +
 .../sfm/client/registry/SFMMenuScreens.java   |   2 +
 .../render/LibraryBlockEntityRenderer.java    | 117 +++++++
 .../sfm/client/screen/LibraryScreen.java      | 256 ++++++++++++++
 ...MTextEditScreenLibraryDiskOpenContext.java |  20 ++
 .../sfm/common/block/LibraryBlock.java        |  53 +++
 .../blockentity/LibraryBlockEntity.java       | 329 ++++++++++++++----
 .../blockentity/ManagerBlockEntity.java       |  62 +++-
 .../containermenu/LibraryContainerMenu.java   | 238 +++++++++++++
 .../ca/teamdman/sfm/common/item/DiskItem.java |  14 +-
 .../common/localization/LocalizationKeys.java |  12 +
 ...erverboundLibraryDiskSetProgramPacket.java |  98 ++++++
 .../program/linting/MacroUsageLinter.java     |   5 +
 .../program/linting/ProtocolUsageLinter.java  |   5 +
 .../linting/StructDefinitionLinter.java       |   5 +
 .../sfm/common/registry/SFMMenus.java         |  40 +++
 .../sfm/common/registry/SFMPackets.java       |   1 +
 .../java/ca/teamdman/sfml/ast/ASTBuilder.java |  47 ++-
 .../sfml/program_builder/ProgramBuilder.java  |  14 +
 .../sfm/textures/block/library_back.png       | Bin 0 -> 119 bytes
 .../assets/sfm/textures/block/library_bot.png | Bin 0 -> 158 bytes
 .../sfm/textures/block/library_front.png      | Bin 0 -> 140 bytes
 .../sfm/textures/block/library_side.png       | Bin 0 -> 148 bytes
 .../assets/sfm/textures/block/library_top.png | Bin 0 -> 160 bytes
 .../sfm/textures/gui/container/library.png    | Bin 0 -> 1728 bytes
 37 files changed, 1362 insertions(+), 80 deletions(-)
 create mode 100644 src/generated/resources/assets/sfm/blockstates/library.json
 create mode 100644 src/generated/resources/assets/sfm/models/block/library.json
 create mode 100644 src/generated/resources/assets/sfm/models/item/library.json
 create mode 100644 src/generated/resources/data/sfm/loot_tables/blocks/library.json
 create mode 100644 src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java
 create mode 100644 src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
 create mode 100644 src/main/java/ca/teamdman/sfm/client/text_editor/SFMTextEditScreenLibraryDiskOpenContext.java
 create mode 100644 src/main/java/ca/teamdman/sfm/common/containermenu/LibraryContainerMenu.java
 create mode 100644 src/main/java/ca/teamdman/sfm/common/net/ServerboundLibraryDiskSetProgramPacket.java
 create mode 100644 src/main/resources/assets/sfm/textures/block/library_back.png
 create mode 100644 src/main/resources/assets/sfm/textures/block/library_bot.png
 create mode 100644 src/main/resources/assets/sfm/textures/block/library_front.png
 create mode 100644 src/main/resources/assets/sfm/textures/block/library_side.png
 create mode 100644 src/main/resources/assets/sfm/textures/block/library_top.png
 create mode 100644 src/main/resources/assets/sfm/textures/gui/container/library.png

diff --git a/src/datagen/java/ca/teamdman/sfm/datagen/SFMBlockStatesAndModelsDatagen.java b/src/datagen/java/ca/teamdman/sfm/datagen/SFMBlockStatesAndModelsDatagen.java
index 337251e07..632840b6c 100644
--- a/src/datagen/java/ca/teamdman/sfm/datagen/SFMBlockStatesAndModelsDatagen.java
+++ b/src/datagen/java/ca/teamdman/sfm/datagen/SFMBlockStatesAndModelsDatagen.java
@@ -33,6 +33,7 @@ protected void registerStatesAndModels() {
         registerWaterTank();
         registerTestBarrel();
         registerBuffer();
+        registerLibrary();
     }
 
     private void registerTestBarrel() {
@@ -244,4 +245,36 @@ private void registerBuffer() {
                 });
 
     }
+
+    private void registerLibrary() {
+        if (SFMBlocks.LIBRARY_BLOCK == null) return;
+
+        // Create a model with different textures for front, back, and sides
+        ModelFile libraryModel = models().cube(
+                SFMBlocks.LIBRARY_BLOCK.getPath(),
+                modLoc("block/library_bot"),    // down
+                modLoc("block/library_top"),    // up
+                modLoc("block/library_front"),  // north (front)
+                modLoc("block/library_back"),   // south (back)
+                modLoc("block/library_side"),   // west
+                modLoc("block/library_side")    // east
+        ).texture("particle", modLoc("block/library_top"));
+
+        // Create variants for each horizontal facing direction
+        getVariantBuilder(SFMBlocks.LIBRARY_BLOCK.get())
+                .forAllStates(state -> {
+                    Direction facing = state.getValue(ca.teamdman.sfm.common.block.LibraryBlock.FACING);
+                    int yRot = switch (facing) {
+                        case NORTH -> 0;
+                        case EAST -> 90;
+                        case SOUTH -> 180;
+                        case WEST -> 270;
+                        default -> 0;
+                    };
+                    return ConfiguredModel.builder()
+                            .modelFile(libraryModel)
+                            .rotationY(yRot)
+                            .build();
+                });
+    }
 }
diff --git a/src/datagen/java/ca/teamdman/sfm/datagen/SFMItemModelsDatagen.java b/src/datagen/java/ca/teamdman/sfm/datagen/SFMItemModelsDatagen.java
index 912b95df0..aad59c9ff 100644
--- a/src/datagen/java/ca/teamdman/sfm/datagen/SFMItemModelsDatagen.java
+++ b/src/datagen/java/ca/teamdman/sfm/datagen/SFMItemModelsDatagen.java
@@ -30,6 +30,9 @@ protected void registerModels() {
         justParent(SFMItems.PRINTING_PRESS_ITEM, SFMBlocks.PRINTING_PRESS_BLOCK);
         justParent(SFMItems.WATER_TANK_ITEM, SFMBlocks.WATER_TANK_BLOCK, "_active");
         justParent(SFMItems.BUFFER_ITEM, SFMBlocks.BUFFER_BLOCK, "_item");
+        if (SFMItems.LIBRARY_ITEM != null) {
+            justParent(SFMItems.LIBRARY_ITEM, SFMBlocks.LIBRARY_BLOCK);
+        }
         basicItem(SFMItems.DISK_ITEM);
         basicItem(SFMItems.LABEL_GUN_ITEM);
         basicItem(SFMItems.EXPERIENCE_GOOP_ITEM);
diff --git a/src/datagen/java/ca/teamdman/sfm/datagen/SFMLootTablesDatagen.java b/src/datagen/java/ca/teamdman/sfm/datagen/SFMLootTablesDatagen.java
index 9101d66d0..7b34ba56d 100644
--- a/src/datagen/java/ca/teamdman/sfm/datagen/SFMLootTablesDatagen.java
+++ b/src/datagen/java/ca/teamdman/sfm/datagen/SFMLootTablesDatagen.java
@@ -27,6 +27,9 @@ protected void populate(BlockLootWriter writer) {
         writer.dropOther(SFMBlocks.FANCY_CABLE_FACADE_BLOCK, SFMBlocks.FANCY_CABLE_BLOCK);
         writer.dropSelf(SFMBlocks.PRINTING_PRESS_BLOCK);
         writer.dropSelf(SFMBlocks.WATER_TANK_BLOCK);
+        if (SFMBlocks.LIBRARY_BLOCK != null) {
+            writer.dropSelf(SFMBlocks.LIBRARY_BLOCK);
+        }
     }
 
     @Override
diff --git a/src/generated/resources/.cache/67cce32b1c3cbbcb1f646605f4914e3f196986c2 b/src/generated/resources/.cache/67cce32b1c3cbbcb1f646605f4914e3f196986c2
index e6d438d78..453716f0f 100644
--- a/src/generated/resources/.cache/67cce32b1c3cbbcb1f646605f4914e3f196986c2
+++ b/src/generated/resources/.cache/67cce32b1c3cbbcb1f646605f4914e3f196986c2
@@ -1,9 +1,10 @@
-// 1.19.2	2025-09-22T22:24:00.9129422	LootTables
+// 1.19.2	2026-01-24T23:53:42.6110462	LootTables
 530958bfa0a0340b5c16ed70d416bfe5fb8776de data/sfm/loot_tables/blocks/buffer.json
 5286db740244722d7db672fc22de815fdd8ab330 data/sfm/loot_tables/blocks/cable.json
 5286db740244722d7db672fc22de815fdd8ab330 data/sfm/loot_tables/blocks/cable_facade.json
 9362833df3c9ef338cf4648460e7e1185154e2d7 data/sfm/loot_tables/blocks/fancy_cable.json
 9362833df3c9ef338cf4648460e7e1185154e2d7 data/sfm/loot_tables/blocks/fancy_cable_facade.json
+d5c24c23a8c72dc72bbb491ec361f96c38825f07 data/sfm/loot_tables/blocks/library.json
 ef4bb95208a13cbe51de891c102654406caee78e data/sfm/loot_tables/blocks/manager.json
 c0a6bdf7e2d285eb10d05e1515ffede8d52f6c0f data/sfm/loot_tables/blocks/printing_press.json
 e92e583664aee9b10bfcfe8b3d01f2c71e7017f7 data/sfm/loot_tables/blocks/tunnelled_manager.json
diff --git a/src/generated/resources/.cache/726a4eaaa226cb50028c5f3f85d691417b67903b b/src/generated/resources/.cache/726a4eaaa226cb50028c5f3f85d691417b67903b
index 2ce6eddb1..736fb7e59 100644
--- a/src/generated/resources/.cache/726a4eaaa226cb50028c5f3f85d691417b67903b
+++ b/src/generated/resources/.cache/726a4eaaa226cb50028c5f3f85d691417b67903b
@@ -1,4 +1,4 @@
-// 1.19.2	2025-09-22T22:24:00.9074388	Item Models: sfm
+// 1.19.2	2026-01-25T00:08:43.9099939	Item Models: sfm
 c30f68ac136d6a8ae24eee7845de7afb19597988 assets/sfm/models/item/buffer.json
 8518af52bb22ef1d984719f3534ff29e08cca857 assets/sfm/models/item/cable.json
 bee75adb2bb431a6b671015aa9bac0d68a98f5fb assets/sfm/models/item/disk.json
@@ -6,6 +6,7 @@ bee75adb2bb431a6b671015aa9bac0d68a98f5fb assets/sfm/models/item/disk.json
 2c8c32d785bfc59bf23083eff8838054ee580570 assets/sfm/models/item/form.json
 a74b029bcf88d674c6a4c4eaece9426cfd9c4533 assets/sfm/models/item/form_base.json
 a70b1032681b30f1066fdfb8b28870e87e51c261 assets/sfm/models/item/labelgun.json
+19cd878c54f1849d9d3f4f851f09445f06afee4c assets/sfm/models/item/library.json
 e945e739059a159bb1d4de5af118d412b50aae6c assets/sfm/models/item/manager.json
 d35a3dbb1180878d85e94f3f00812e5f34a4b2da assets/sfm/models/item/network_tool.json
 cd81e93f92577f247bb4bd12e01494d83e0733ce assets/sfm/models/item/printing_press.json
diff --git a/src/generated/resources/.cache/bf0ffec7956ce36aba0a993095f41e47d655813b b/src/generated/resources/.cache/bf0ffec7956ce36aba0a993095f41e47d655813b
index b1e49ed7c..d2bafa689 100644
--- a/src/generated/resources/.cache/bf0ffec7956ce36aba0a993095f41e47d655813b
+++ b/src/generated/resources/.cache/bf0ffec7956ce36aba0a993095f41e47d655813b
@@ -1,9 +1,10 @@
-// 1.19.2	2025-10-15T14:33:21.7675717	Block States: sfm
+// 1.19.2	2026-01-25T00:08:43.9119934	Block States: sfm
 6a4e3ee4c0c8d070519225c335fe0857b0b627fd assets/sfm/blockstates/buffer.json
 f303dc233cde263e111cfdb2e2cbc48b93521724 assets/sfm/blockstates/cable.json
 f303dc233cde263e111cfdb2e2cbc48b93521724 assets/sfm/blockstates/cable_facade.json
 0a672c9322f8bb4628d2c78d1f2d4edf3099aa31 assets/sfm/blockstates/fancy_cable.json
 0a672c9322f8bb4628d2c78d1f2d4edf3099aa31 assets/sfm/blockstates/fancy_cable_facade.json
+735956f079981e4f5ccb931bd90f54a6b2b75fd2 assets/sfm/blockstates/library.json
 01e9d7d54169b7f6bbd287f4b896629f66f25305 assets/sfm/blockstates/manager.json
 a351025a2054b6ce2ddc21dc14734cc8b5b635bc assets/sfm/blockstates/printing_press.json
 9be344941a18ad0d8dccbcd6536d52bf7295c1c8 assets/sfm/blockstates/test_barrel.json
@@ -19,6 +20,7 @@ f3c25839c6554e631061f91277bc687aebc38fd7 assets/sfm/blockstates/water_tank.json
 a76567fd4e65d191d69cf166b98776786d47a8e2 assets/sfm/models/block/cable.json
 7b8c954b87699a007b3d7aa3558bf7892b838975 assets/sfm/models/block/fancy_cable_connection.json
 7ba1003f6a1c077779c8e51166e1d134874844a8 assets/sfm/models/block/fancy_cable_core.json
+bacc43d799e70733161cc879b677d223120ce0d0 assets/sfm/models/block/library.json
 953313d31931040aa2bd9a8742d4a54a2c632b8d assets/sfm/models/block/manager.json
 369e3217e52fc9f71d3e4a83b9175bb4e36dbac0 assets/sfm/models/block/test_barrel_tank.json
 fbd4f97091c4dadead5a68954d148efb4ecb5ff6 assets/sfm/models/block/tunnelled_manager.json
diff --git a/src/generated/resources/.cache/c622617f6fabf890a00b9275cd5f643584a8a2c8 b/src/generated/resources/.cache/c622617f6fabf890a00b9275cd5f643584a8a2c8
index a941c2b01..3cf1a1845 100644
--- a/src/generated/resources/.cache/c622617f6fabf890a00b9275cd5f643584a8a2c8
+++ b/src/generated/resources/.cache/c622617f6fabf890a00b9275cd5f643584a8a2c8
@@ -1,2 +1,2 @@
-// 1.19.2	2026-01-17T14:31:43.7433283	Languages: en_us
-d99e0d153788033acd2b6f401b075f3c02670725 assets/sfm/lang/en_us.json
+// 1.19.2	2026-01-24T23:53:42.6100447	Languages: en_us
+f5abacc648082ac18ffe913436c93452ff59c12e assets/sfm/lang/en_us.json
diff --git a/src/generated/resources/assets/sfm/blockstates/library.json b/src/generated/resources/assets/sfm/blockstates/library.json
new file mode 100644
index 000000000..660d5f632
--- /dev/null
+++ b/src/generated/resources/assets/sfm/blockstates/library.json
@@ -0,0 +1,19 @@
+{
+  "variants": {
+    "facing=east": {
+      "model": "sfm:block/library",
+      "y": 90
+    },
+    "facing=north": {
+      "model": "sfm:block/library"
+    },
+    "facing=south": {
+      "model": "sfm:block/library",
+      "y": 180
+    },
+    "facing=west": {
+      "model": "sfm:block/library",
+      "y": 270
+    }
+  }
+}
\ No newline at end of file
diff --git a/src/generated/resources/assets/sfm/lang/en_us.json b/src/generated/resources/assets/sfm/lang/en_us.json
index acd5d4e2e..758ba2d04 100644
--- a/src/generated/resources/assets/sfm/lang/en_us.json
+++ b/src/generated/resources/assets/sfm/lang/en_us.json
@@ -4,6 +4,7 @@
   "block.sfm.cable_facade": "Inventory Cable Facade",
   "block.sfm.fancy_cable": "Fancy Inventory Cable",
   "block.sfm.fancy_cable_facade": "Fancy Inventory Cable Facade",
+  "block.sfm.library": "SFML Library Block",
   "block.sfm.manager": "Factory Manager",
   "block.sfm.printing_press": "Printing Press",
   "block.sfm.printing_press.tooltip": "Place with an air gap below a downward facing piston. Extend the piston to use.",
@@ -17,6 +18,7 @@
   "chat.sfm.config_update_and_sync_result.internal_failure": "Something went wrong while updating the SFM config, I have no idea if changes were made. Check the server logs.",
   "chat.sfm.config_update_and_sync_result.invalid_config": "The provided SFM config was invalid, no changes were made.",
   "chat.sfm.config_update_and_sync_result.success": "Successfully updated SFM config.",
+  "container.sfm.library": "SFML Library",
   "container.sfm.manager": "Factory Manager",
   "container.sfm.test_barrel_tank": "Test Barrel Tank",
   "gui.jei.category.sfm.falling_anvil": "Falling Anvil",
@@ -216,6 +218,7 @@
   "log.sfm.statement.tick.io.move_to.destination_tracker_reject": "Destination tracker rejected the transfer, skipping",
   "log.sfm.statement.tick.io.move_to.end": "Moved %d %s - source=%s, dest=%s",
   "log.sfm.statement.tick.io.move_to.extracted": "Extracted %d from slot %d",
+  "log.sfm.statement.tick.io.move_to.extracted_nothing": "extracted nothing, marking this input slot as done",
   "log.sfm.statement.tick.io.move_to.retention_obligation": "Promised to leave %d in the source slot, still obligated to leave %d",
   "log.sfm.statement.tick.io.move_to.retention_obligation_no_move": "Nothing to move after retention obligations, marking source slot done and skipping",
   "log.sfm.statement.tick.io.move_to.stack_limit_no_move": "Max transferable dest=%d, source=%d, stack limit=%d; new toMove=%d",
@@ -234,6 +237,8 @@
   "program.sfm.error.compile_failed_with_errors": "Failed to compile with %d errors.",
   "program.sfm.error.compile_success_with_warnings": "Successfully compiled \"%s\" with %d warnings.",
   "program.sfm.error.disallowed_resource_type": "Program references a disallowed resource type \"%s\"",
+  "program.sfm.error.library_has_errors": "Library \"%s\" has compilation errors.",
+  "program.sfm.error.library_not_found": "Library \"%s\" not found in cable network.",
   "program.sfm.error.literal": "%s",
   "program.sfm.error.malformed_resource_type": "Program has a malformed resource type \"%s\".\nReminder: Resource types must be literals, not wildcards.",
   "program.sfm.error.unknown_resource_type": "Program references an unknown resource type \"%s\"",
@@ -257,6 +262,11 @@
   "program.sfm.warnings.unknown_resource_id": "Resource \"%s\" was not found.",
   "program.sfm.warnings.unused_input_label": "Statement \"%s\" at %s inputs \"%s\" from \"%s\" but no future output statement consume \"%s\".",
   "program.sfm.warnings.unused_label": "Label \"%s\" is used in code but not assigned in the world.",
+  "program.sfm.warnings.unused_library": "Library \"%s\" is imported but none of its definitions are used.",
+  "program.sfm.warnings.unused_macro": "Macro \"%s\" is defined but never expanded.",
+  "program.sfm.warnings.unused_protocol": "Protocol \"%s\" is defined but never used.",
+  "program.sfm.warnings.unused_struct": "Struct \"%s\" is defined but never instantiated.",
+  "program.sfm.warnings.unused_struct_instance": "Struct instance \"%s\" is defined but never used in a USING clause.",
   "sfm.label_gun.view_mode.show_only_active_and_targeted": "Showing blocks with active label. Cycle mode in gui or with %s",
   "sfm.label_gun.view_mode.show_only_targeted": "Showing only targeted block labels. Cycle mode in gui or with %s",
   "sfm.network_tool.reminder_overlay": "Toggle network tool overlay with %s"
diff --git a/src/generated/resources/assets/sfm/models/block/library.json b/src/generated/resources/assets/sfm/models/block/library.json
new file mode 100644
index 000000000..95abadc4a
--- /dev/null
+++ b/src/generated/resources/assets/sfm/models/block/library.json
@@ -0,0 +1,12 @@
+{
+  "parent": "minecraft:block/cube",
+  "textures": {
+    "down": "sfm:block/library_bot",
+    "east": "sfm:block/library_side",
+    "north": "sfm:block/library_front",
+    "particle": "sfm:block/library_top",
+    "south": "sfm:block/library_back",
+    "up": "sfm:block/library_top",
+    "west": "sfm:block/library_side"
+  }
+}
\ No newline at end of file
diff --git a/src/generated/resources/assets/sfm/models/item/library.json b/src/generated/resources/assets/sfm/models/item/library.json
new file mode 100644
index 000000000..ac40f054b
--- /dev/null
+++ b/src/generated/resources/assets/sfm/models/item/library.json
@@ -0,0 +1,3 @@
+{
+  "parent": "sfm:block/library"
+}
\ No newline at end of file
diff --git a/src/generated/resources/data/sfm/loot_tables/blocks/library.json b/src/generated/resources/data/sfm/loot_tables/blocks/library.json
new file mode 100644
index 000000000..9bae64f51
--- /dev/null
+++ b/src/generated/resources/data/sfm/loot_tables/blocks/library.json
@@ -0,0 +1,20 @@
+{
+  "type": "minecraft:block",
+  "pools": [
+    {
+      "bonus_rolls": 0.0,
+      "conditions": [
+        {
+          "condition": "minecraft:survives_explosion"
+        }
+      ],
+      "entries": [
+        {
+          "type": "minecraft:item",
+          "name": "sfm:library"
+        }
+      ],
+      "rolls": 1.0
+    }
+  ]
+}
\ No newline at end of file
diff --git a/src/main/java/ca/teamdman/sfm/client/registry/SFMBlockEntityRenderers.java b/src/main/java/ca/teamdman/sfm/client/registry/SFMBlockEntityRenderers.java
index 148581bb8..87c736246 100644
--- a/src/main/java/ca/teamdman/sfm/client/registry/SFMBlockEntityRenderers.java
+++ b/src/main/java/ca/teamdman/sfm/client/registry/SFMBlockEntityRenderers.java
@@ -1,6 +1,7 @@
 package ca.teamdman.sfm.client.registry;
 
 import ca.teamdman.sfm.SFM;
+import ca.teamdman.sfm.client.render.LibraryBlockEntityRenderer;
 import ca.teamdman.sfm.client.render.PrintingPressBlockEntityRenderer;
 import ca.teamdman.sfm.common.registry.SFMBlockEntities;
 import net.minecraftforge.api.distmarker.Dist;
@@ -16,5 +17,11 @@ public static void onRegisterRenderers(EntityRenderersEvent.RegisterRenderers ev
                 SFMBlockEntities.PRINTING_PRESS_BLOCK_ENTITY.get(),
                 PrintingPressBlockEntityRenderer::new
         );
+        if (SFMBlockEntities.LIBRARY_BLOCK_ENTITY != null) {
+            event.registerBlockEntityRenderer(
+                    SFMBlockEntities.LIBRARY_BLOCK_ENTITY.get(),
+                    LibraryBlockEntityRenderer::new
+            );
+        }
     }
 }
diff --git a/src/main/java/ca/teamdman/sfm/client/registry/SFMMenuScreens.java b/src/main/java/ca/teamdman/sfm/client/registry/SFMMenuScreens.java
index ffa5beaf9..987b20602 100644
--- a/src/main/java/ca/teamdman/sfm/client/registry/SFMMenuScreens.java
+++ b/src/main/java/ca/teamdman/sfm/client/registry/SFMMenuScreens.java
@@ -1,5 +1,6 @@
 package ca.teamdman.sfm.client.registry;
 
+import ca.teamdman.sfm.client.screen.LibraryScreen;
 import ca.teamdman.sfm.client.screen.ManagerScreen;
 import ca.teamdman.sfm.client.screen.TestBarrelTankScreen;
 import ca.teamdman.sfm.common.registry.SFMMenus;
@@ -9,5 +10,6 @@ public class SFMMenuScreens {
     public static void register() {
         MenuScreens.register(SFMMenus.MANAGER_MENU.get(), ManagerScreen::new);
         MenuScreens.register(SFMMenus.TEST_BARREL_TANK_MENU.get(), TestBarrelTankScreen::new);
+        MenuScreens.register(SFMMenus.LIBRARY_MENU.get(), LibraryScreen::new);
     }
 }
diff --git a/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java b/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java
new file mode 100644
index 000000000..9986b5965
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java
@@ -0,0 +1,117 @@
+package ca.teamdman.sfm.client.render;
+
+import ca.teamdman.sfm.common.block.LibraryBlock;
+import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
+import com.mojang.blaze3d.systems.RenderSystem;
+import com.mojang.blaze3d.vertex.*;
+import com.mojang.math.Matrix4f;
+import com.mojang.math.Vector3f;
+import net.minecraft.client.renderer.GameRenderer;
+import net.minecraft.client.renderer.MultiBufferSource;
+import net.minecraft.client.renderer.blockentity.BlockEntityRenderer;
+import net.minecraft.client.renderer.blockentity.BlockEntityRendererProvider;
+import net.minecraft.core.Direction;
+
+/**
+ * Renders disk slot indicators on the front face of the library block.
+ * Shows amber lights for occupied slots, matching their physical positions.
+ */
+public class LibraryBlockEntityRenderer implements BlockEntityRenderer<LibraryBlockEntity> {
+
+    // Amber phosphor color (matching the UI palette)
+    private static final float AMBER_R = 204f / 255f;
+    private static final float AMBER_G = 150f / 255f;
+    private static final float AMBER_B = 64f / 255f;
+
+    // Slot layout constants (in block units, 0-1 range)
+    private static final float SLOT_SIZE = 1.0f / 16.0f;  // 1 pixel
+    private static final float SLOT_SPACING = 2.0f / 16.0f;  // 2 pixels between slots
+
+    // Starting position for the slot grid
+    private static final float GRID_START_X = 3.0f / 16.0f;
+    private static final float ROW1_Y = 9.0f / 16.0f;
+    private static final float ROW2_Y = 12.0f / 16.0f;
+
+    // Z offset to prevent z-fighting
+    private static final float Z_OFFSET = -0.001f;
+
+    public LibraryBlockEntityRenderer(BlockEntityRendererProvider.Context context) {
+    }
+
+    @Override
+    public void render(
+            LibraryBlockEntity blockEntity,
+            float partialTick,
+            PoseStack poseStack,
+            MultiBufferSource bufferSource,
+            int packedLight,
+            int packedOverlay
+    ) {
+        int diskMask = blockEntity.getDiskSlotMask();
+        if (diskMask == 0) return;
+
+        Direction facing = blockEntity.getBlockState().getValue(LibraryBlock.FACING);
+
+        poseStack.pushPose();
+
+        // Move to center of block
+        poseStack.translate(0.5, 0.5, 0.5);
+
+        // Rotate based on facing direction
+        // Note: blockstate uses clockwise rotation, but renderer uses counter-clockwise,
+        // so EAST/WEST values are inverted (90 <-> 270)
+        float rotation = switch (facing) {
+            case NORTH -> 0;
+            case SOUTH -> 180;
+            case EAST -> 270;
+            case WEST -> 90;
+            default -> 0;
+        };
+        poseStack.mulPose(Vector3f.YP.rotationDegrees(rotation));
+
+        // Move back from center
+        poseStack.translate(-0.5, -0.5, -0.5);
+
+        // Set up rendering for colored quads
+        RenderSystem.enableDepthTest();
+        RenderSystem.setShader(GameRenderer::getPositionColorShader);
+
+        Tesselator tesselator = Tesselator.getInstance();
+        BufferBuilder buffer = tesselator.getBuilder();
+
+        Matrix4f matrix = poseStack.last().pose();
+
+        buffer.begin(VertexFormat.Mode.QUADS, DefaultVertexFormat.POSITION_COLOR);
+
+        // Render indicators for each occupied slot
+        for (int slot = 0; slot < LibraryBlockEntity.DISK_SLOT_COUNT; slot++) {
+            if ((diskMask & (1 << slot)) != 0) {
+                renderSlotIndicator(buffer, matrix, slot);
+            }
+        }
+
+        tesselator.end();
+
+        poseStack.popPose();
+    }
+
+    private void renderSlotIndicator(BufferBuilder buffer, Matrix4f matrix, int slot) {
+        int row = slot / 5;
+        int col = 4 - (slot % 5);  // Mirror column to match GUI layout
+
+        float x = GRID_START_X + col * SLOT_SPACING;
+        float y = (row == 0) ? ROW1_Y : ROW2_Y;
+
+        float x1 = x;
+        float x2 = x + SLOT_SIZE;
+        float y1 = 1.0f - y - SLOT_SIZE;
+        float y2 = 1.0f - y;
+        float z = Z_OFFSET;
+
+        // Quad on the north face (z=0)
+        buffer.vertex(matrix, x1, y1, z).color(AMBER_R, AMBER_G, AMBER_B, 1.0f).endVertex();
+        buffer.vertex(matrix, x1, y2, z).color(AMBER_R, AMBER_G, AMBER_B, 1.0f).endVertex();
+        buffer.vertex(matrix, x2, y2, z).color(AMBER_R, AMBER_G, AMBER_B, 1.0f).endVertex();
+        buffer.vertex(matrix, x2, y1, z).color(AMBER_R, AMBER_G, AMBER_B, 1.0f).endVertex();
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java b/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
new file mode 100644
index 000000000..6bb42b14b
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
@@ -0,0 +1,256 @@
+package ca.teamdman.sfm.client.screen;
+
+import ca.teamdman.sfm.client.text_editor.SFMTextEditScreenLibraryDiskOpenContext;
+import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
+import ca.teamdman.sfm.common.containermenu.LibraryContainerMenu;
+import ca.teamdman.sfm.common.containermenu.LibraryContainerMenu.LibraryEntry;
+import ca.teamdman.sfm.common.item.DiskItem;
+import ca.teamdman.sfm.common.net.ServerboundLibraryDiskSetProgramPacket;
+import ca.teamdman.sfm.common.registry.SFMPackets;
+import ca.teamdman.sfm.common.util.SFMResourceLocation;
+import com.mojang.blaze3d.systems.RenderSystem;
+import com.mojang.blaze3d.vertex.PoseStack;
+import net.minecraft.client.gui.screens.inventory.AbstractContainerScreen;
+import net.minecraft.client.renderer.GameRenderer;
+import net.minecraft.network.chat.Component;
+import net.minecraft.resources.ResourceLocation;
+import net.minecraft.world.entity.player.Inventory;
+import net.minecraft.world.item.ItemStack;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Client-side screen for the library block.
+ * Shows disk slots and displays available library names from inserted disks
+ * in a computer terminal-style panel on the left.
+ */
+public class LibraryScreen extends AbstractContainerScreen<LibraryContainerMenu> {
+    private static final ResourceLocation BACKGROUND_TEXTURE_LOCATION = SFMResourceLocation.fromSFMPath(
+            "textures/gui/container/library.png"
+    );
+
+    private static final int PANEL_WIDTH = 120;
+    private static final int PANEL_GAP = 4;
+
+    // Bezel/Frame colors (warm dark grays like old monitor plastic)
+    private static final int BEZEL_OUTER = 0xFF2D2A26;
+    private static final int BEZEL_INNER = 0xFF1A1816;
+    private static final int BEZEL_HIGHLIGHT = 0xFF3D3A36;
+
+    // Screen colors
+    private static final int SCREEN_BG = 0xFF0D0C0A;
+    private static final int SCREEN_EDGE = 0xFF050504;
+
+    // Amber phosphor text colors
+    private static final int TEXT_HEADER = 0xFFFFB84D;
+    private static final int TEXT_NORMAL = 0xFFCC9640;
+    private static final int TEXT_HOVER = 0xFFFFD080;
+    private static final int TEXT_DIM = 0xFF806020;
+
+    // Effects
+    private static final int CURSOR_GLOW = 0x30FFB84D;
+
+    private int hoveredLibraryEntry = -1;
+
+    public LibraryScreen(
+            LibraryContainerMenu menu,
+            Inventory inv,
+            Component title
+    ) {
+        super(menu, inv, title);
+    }
+
+    @Override
+    protected void init() {
+        super.init();
+    }
+
+    @Override
+    protected void containerTick() {
+        super.containerTick();
+        refreshLibraryEntries();
+    }
+
+    private void refreshLibraryEntries() {
+        List<LibraryEntry> entries = new ArrayList<>();
+        for (int i = 0; i < LibraryBlockEntity.DISK_SLOT_COUNT; i++) {
+            ItemStack disk = menu.CONTAINER.getItem(i);
+            if (disk.isEmpty() || !(disk.getItem() instanceof DiskItem)) continue;
+
+            String source = DiskItem.getProgramString(disk);
+            String name = LibraryBlockEntity.extractName(source);
+            if (name != null && !name.isEmpty()) {
+                entries.add(new LibraryEntry(name, i));
+            }
+        }
+        menu.libraryEntries = entries;
+    }
+
+    private void openEditorForSlot(int slotIndex) {
+        ItemStack disk = menu.CONTAINER.getItem(slotIndex);
+        if (disk.isEmpty() || !(disk.getItem() instanceof DiskItem)) return;
+
+        String source = DiskItem.getProgramString(disk);
+        SFMScreenChangeHelpers.showProgramEditScreen(new SFMTextEditScreenLibraryDiskOpenContext(
+                source,
+                newSource -> {
+                    SFMPackets.sendToServer(new ServerboundLibraryDiskSetProgramPacket(
+                            menu.containerId, menu.LIBRARY_POSITION, slotIndex, newSource));
+                    DiskItem.setProgram(disk, newSource);
+                    refreshLibraryEntries();
+                }
+        ));
+    }
+
+    @Override
+    public boolean mouseClicked(double mouseX, double mouseY, int button) {
+        // Click on library entry in panel
+        if (button == 0 && hoveredLibraryEntry >= 0 && hoveredLibraryEntry < menu.libraryEntries.size()) {
+            LibraryEntry entry = menu.libraryEntries.get(hoveredLibraryEntry);
+            openEditorForSlot(entry.slotIndex());
+            return true;
+        }
+        return super.mouseClicked(mouseX, mouseY, button);
+    }
+
+    @Override
+    public void render(
+            PoseStack poseStack,
+            int mx,
+            int my,
+            float partialTicks
+    ) {
+        this.renderBackground(poseStack);
+        super.render(poseStack, mx, my, partialTicks);
+        this.renderTooltip(poseStack, mx, my);
+
+        // Render library list in the panel
+        int panelX = this.leftPos - PANEL_WIDTH - PANEL_GAP;
+        int screenX = panelX + 5;
+        int screenY = this.topPos + 5;
+        int screenRight = panelX + PANEL_WIDTH - 5;
+
+        // Header area with subtle background
+        int headerY = screenY + 2;
+        fill(poseStack, screenX + 3, headerY - 1, screenRight - 3, headerY + font.lineHeight + 2, 0x20FFB84D);
+
+        // Header text - centered
+        String header = "LIBRARY INDEX";
+        int headerWidth = font.width(header);
+        int headerX = screenX + (PANEL_WIDTH - 10 - headerWidth) / 2;
+        font.drawShadow(poseStack, header, headerX, headerY, TEXT_HEADER);
+
+        // Divider line
+        int dividerY = headerY + font.lineHeight + 4;
+        fill(poseStack, screenX + 8, dividerY, screenRight - 8, dividerY + 1, TEXT_DIM);
+
+        // Content area starts below divider
+        int contentY = dividerY + 6;
+        int textX = screenX + 6;
+
+        // Reset hover state
+        hoveredLibraryEntry = -1;
+
+        if (menu.libraryEntries.isEmpty()) {
+            // Show hint when no libraries are available
+            font.drawShadow(poseStack, "No libraries found", textX, contentY, TEXT_DIM);
+            contentY += font.lineHeight + 2;
+            font.drawShadow(poseStack, "Insert disks with", textX, contentY, TEXT_DIM);
+            contentY += font.lineHeight;
+            font.drawShadow(poseStack, "NAME statements", textX, contentY, TEXT_DIM);
+        } else {
+            // Draw library entries with slot numbers right-aligned
+            for (int i = 0; i < menu.libraryEntries.size(); i++) {
+                LibraryEntry entry = menu.libraryEntries.get(i);
+
+                // Hover detection - use full row width
+                boolean hovered = mx >= screenX + 3 && mx <= screenRight - 3
+                        && my >= contentY - 1 && my <= contentY + font.lineHeight + 1;
+
+                if (hovered) {
+                    hoveredLibraryEntry = i;
+                    // Draw hover glow background
+                    fill(poseStack, screenX + 3, contentY - 1, screenRight - 3, contentY + font.lineHeight + 1, CURSOR_GLOW);
+                }
+
+                // Cursor indicator and library name
+                String cursor = hovered ? "> " : "  ";
+                int color = hovered ? TEXT_HOVER : TEXT_NORMAL;
+                font.drawShadow(poseStack, cursor + entry.name(), textX, contentY, color);
+
+                // Slot number right-aligned
+                String slotText = "[" + (entry.slotIndex()) + "]";
+                int slotWidth = font.width(slotText);
+                font.drawShadow(poseStack, slotText, screenRight - 6 - slotWidth, contentY, TEXT_DIM);
+
+                contentY += font.lineHeight + 3;
+
+                // Don't overflow past the panel
+                if (contentY > this.topPos + this.imageHeight - font.lineHeight - 10) break;
+            }
+        }
+    }
+
+    @Override
+    protected void renderLabels(
+            PoseStack poseStack,
+            int mx,
+            int my
+    ) {
+        // Draw title centered in the container area
+        this.font.draw(poseStack, this.title, (float) this.titleLabelX, (float) this.titleLabelY, 4210752);
+        this.font.draw(poseStack, this.playerInventoryTitle, (float) this.inventoryLabelX, (float) this.inventoryLabelY, 4210752);
+    }
+
+    @Override
+    protected void renderBg(
+            PoseStack matrixStack,
+            float partialTicks,
+            int mx,
+            int my
+    ) {
+        // Render the computer panel with CRT monitor bezel effect
+        int panelX = this.leftPos - PANEL_WIDTH - PANEL_GAP;
+        int panelY = this.topPos;
+        int panelRight = panelX + PANEL_WIDTH;
+        int panelBottom = panelY + imageHeight;
+
+        // Outer bezel (3px frame)
+        fill(matrixStack, panelX, panelY, panelRight, panelBottom, BEZEL_OUTER);
+
+        // Bezel highlight (top and left edges, 1px)
+        fill(matrixStack, panelX, panelY, panelRight, panelY + 1, BEZEL_HIGHLIGHT);
+        fill(matrixStack, panelX, panelY, panelX + 1, panelBottom, BEZEL_HIGHLIGHT);
+
+        // Inner bezel shadow (bottom and right, 1px)
+        fill(matrixStack, panelX, panelBottom - 1, panelRight, panelBottom, SCREEN_EDGE);
+        fill(matrixStack, panelRight - 1, panelY, panelRight, panelBottom, SCREEN_EDGE);
+
+        // Inner frame (2px inset)
+        int innerX = panelX + 3;
+        int innerY = panelY + 3;
+        int innerRight = panelRight - 3;
+        int innerBottom = panelBottom - 3;
+        fill(matrixStack, innerX, innerY, innerRight, innerBottom, BEZEL_INNER);
+
+        // Screen area (the "CRT glass")
+        int screenX = innerX + 2;
+        int screenY = innerY + 2;
+        int screenRight = innerRight - 2;
+        int screenBottom = innerBottom - 2;
+        fill(matrixStack, screenX, screenY, screenRight, screenBottom, SCREEN_BG);
+
+        // Screen edge darkening (vignette effect - 1px darker border inside screen)
+        fill(matrixStack, screenX, screenY, screenRight, screenY + 1, SCREEN_EDGE);
+        fill(matrixStack, screenX, screenY, screenX + 1, screenBottom, SCREEN_EDGE);
+
+        // Render the main container background
+        RenderSystem.setShader(GameRenderer::getPositionTexShader);
+        RenderSystem.setShaderColor(1f, 1f, 1f, 1f);
+        RenderSystem.setShaderTexture(0, BACKGROUND_TEXTURE_LOCATION);
+        int i = (this.width - this.imageWidth) / 2;
+        int j = (this.height - this.imageHeight) / 2;
+        blit(matrixStack, i, j, 0, 0, this.imageWidth, this.imageHeight);
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfm/client/text_editor/SFMTextEditScreenLibraryDiskOpenContext.java b/src/main/java/ca/teamdman/sfm/client/text_editor/SFMTextEditScreenLibraryDiskOpenContext.java
new file mode 100644
index 000000000..925f3251f
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfm/client/text_editor/SFMTextEditScreenLibraryDiskOpenContext.java
@@ -0,0 +1,20 @@
+package ca.teamdman.sfm.client.text_editor;
+
+import ca.teamdman.sfm.common.label.LabelPositionHolder;
+
+import java.util.function.Consumer;
+
+/**
+ * Context for opening the text editor for a disk in a library block.
+ * Library disks don't have label positions, so we use an empty holder.
+ */
+public record SFMTextEditScreenLibraryDiskOpenContext(
+        String initialValue,
+        Consumer<String> saveWriter
+) implements ISFMTextEditScreenOpenContext {
+
+    @Override
+    public LabelPositionHolder labelPositionHolder() {
+        return LabelPositionHolder.empty();
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java b/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java
index ed870cb4a..54027292b 100644
--- a/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java
+++ b/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java
@@ -3,8 +3,13 @@
 import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
 import ca.teamdman.sfm.common.cablenetwork.CableNetworkManager;
 import ca.teamdman.sfm.common.cablenetwork.ICableBlock;
+import ca.teamdman.sfm.common.containermenu.LibraryContainerMenu;
 import ca.teamdman.sfm.common.registry.SFMBlockEntities;
 import net.minecraft.core.BlockPos;
+import net.minecraft.server.level.ServerPlayer;
+import net.minecraft.world.InteractionHand;
+import net.minecraft.world.InteractionResult;
+import net.minecraft.world.entity.player.Player;
 import net.minecraft.world.level.Level;
 import net.minecraft.world.level.block.BaseEntityBlock;
 import net.minecraft.world.level.block.Block;
@@ -14,20 +19,44 @@
 import net.minecraft.world.level.block.entity.BlockEntity;
 import net.minecraft.world.level.block.state.BlockBehaviour;
 import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.Containers;
+import net.minecraft.world.level.block.state.StateDefinition;
+import net.minecraft.world.level.block.state.properties.BlockStateProperties;
+import net.minecraft.world.level.block.state.properties.DirectionProperty;
+import net.minecraft.world.item.context.BlockPlaceContext;
 import net.minecraft.world.level.material.Material;
+import net.minecraft.world.phys.BlockHitResult;
+import net.minecraftforge.network.NetworkHooks;
 import org.jetbrains.annotations.Nullable;
 
 /**
  * A block that stores SFML library definitions (protocols, structs, macros).
  * Can be referenced by manager programs via "use library" statements.
+ * The front face shows disk slot indicators via a BlockEntityRenderer.
  */
 public class LibraryBlock extends BaseEntityBlock implements EntityBlock, ICableBlock {
 
+    /**
+     * Property tracking which direction the front face is facing.
+     */
+    public static final DirectionProperty FACING = BlockStateProperties.HORIZONTAL_FACING;
+
     public LibraryBlock() {
         super(BlockBehaviour.Properties
                 .of(Material.PISTON)
                 .destroyTime(1.5f)
                 .sound(SoundType.METAL));
+        registerDefaultState(getStateDefinition().any().setValue(FACING, net.minecraft.core.Direction.NORTH));
+    }
+
+    @Override
+    protected void createBlockStateDefinition(StateDefinition.Builder<Block, BlockState> builder) {
+        builder.add(FACING);
+    }
+
+    @Override
+    public BlockState getStateForPlacement(BlockPlaceContext context) {
+        return defaultBlockState().setValue(FACING, context.getHorizontalDirection().getOpposite());
     }
 
     @Override
@@ -41,6 +70,26 @@ public RenderShape getRenderShape(BlockState state) {
         return SFMBlockEntities.LIBRARY_BLOCK_ENTITY.get().create(pos, state);
     }
 
+    @Override
+    @SuppressWarnings("deprecation")
+    public InteractionResult use(
+            BlockState state,
+            Level level,
+            BlockPos pos,
+            Player player,
+            InteractionHand hand,
+            BlockHitResult hit
+    ) {
+        if (!level.isClientSide() && level.getBlockEntity(pos) instanceof LibraryBlockEntity library) {
+            NetworkHooks.openScreen(
+                    (ServerPlayer) player,
+                    library,
+                    buf -> LibraryContainerMenu.encode(library, buf)
+            );
+        }
+        return InteractionResult.sidedSuccess(level.isClientSide());
+    }
+
     @Override
     @SuppressWarnings("deprecation")
     public void onPlace(
@@ -63,6 +112,10 @@ public void onRemove(
             boolean isMoving
     ) {
         if (!state.is(newState.getBlock())) {
+            // Drop all disks when block is broken
+            if (level.getBlockEntity(pos) instanceof LibraryBlockEntity library) {
+                Containers.dropContents(level, pos, library);
+            }
             CableNetworkManager.onCableRemoved(level, pos);
             super.onRemove(state, level, pos, newState, isMoving);
         }
diff --git a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
index eeae5e1a2..c143ed6bc 100644
--- a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
+++ b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
@@ -1,135 +1,320 @@
 package ca.teamdman.sfm.common.blockentity;
 
+import ca.teamdman.langs.SFMLLexer;
+import ca.teamdman.langs.SFMLParser;
+import ca.teamdman.sfm.common.containermenu.LibraryContainerMenu;
+import ca.teamdman.sfm.common.item.DiskItem;
+import ca.teamdman.sfm.common.localization.LocalizationKeys;
 import ca.teamdman.sfm.common.registry.SFMBlockEntities;
+import ca.teamdman.sfm.common.registry.SFMItems;
+import ca.teamdman.sfm.common.util.SFMContainerUtil;
+import ca.teamdman.sfml.ast.ASTBuilder;
+import ca.teamdman.sfml.ast.MacroDefinition;
+import ca.teamdman.sfml.ast.Program;
+import ca.teamdman.sfml.ast.ProtocolDefinition;
+import ca.teamdman.sfml.ast.StructDefinition;
 import ca.teamdman.sfml.program_builder.LibraryDefinitions;
 import net.minecraft.core.BlockPos;
+import net.minecraft.core.NonNullList;
 import net.minecraft.nbt.CompoundTag;
-import net.minecraft.nbt.ListTag;
-import net.minecraft.nbt.StringTag;
-import net.minecraft.nbt.Tag;
 import net.minecraft.network.chat.Component;
-import net.minecraft.world.MenuProvider;
+import net.minecraft.world.ContainerHelper;
 import net.minecraft.world.entity.player.Inventory;
 import net.minecraft.world.entity.player.Player;
 import net.minecraft.world.inventory.AbstractContainerMenu;
-import net.minecraft.world.level.block.entity.BlockEntity;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.network.protocol.Packet;
+import net.minecraft.network.protocol.game.ClientGamePacketListener;
+import net.minecraft.network.protocol.game.ClientboundBlockEntityDataPacket;
+import net.minecraft.world.level.block.entity.BaseContainerBlockEntity;
 import net.minecraft.world.level.block.state.BlockState;
+import org.antlr.v4.runtime.CharStreams;
+import org.antlr.v4.runtime.CommonTokenStream;
 import org.jetbrains.annotations.Nullable;
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 
 /**
- * Block entity for library blocks that store SFML definitions (protocols, structs, macros).
- * Library blocks can be referenced by manager programs to share common definitions.
+ * Block entity for library blocks that store disks containing SFML definitions.
+ * Library blocks can hold multiple disks, and each disk's NAME becomes the importable path.
+ * Libraries are auto-discovered on the cable network.
  */
-public class LibraryBlockEntity extends BlockEntity implements MenuProvider {
+public class LibraryBlockEntity extends BaseContainerBlockEntity {
 
-    private static final String NBT_KEY_SOURCE = "Source";
+    public static final int DISK_SLOT_COUNT = 10;
 
     /**
-     * The raw SFML source code containing the library definitions.
+     * Pattern to extract NAME from source code.
+     * Matches: NAME "some_name" (case-insensitive)
+     * Supports escaped quotes in the name.
      */
-    private String sourceCode = "";
+    private static final Pattern NAME_PATTERN = Pattern.compile(
+            "(?i)\\bNAME\\s+\"([^\"\\\\]*(\\\\.[^\"\\\\]*)*)\"");
 
-    /**
-     * Cached parsed definitions. Null if not yet parsed or if source is invalid.
-     */
-    @Nullable
-    private LibraryDefinitions cachedDefinitions = null;
-
-    /**
-     * Compilation errors, empty if compilation succeeded.
-     */
-    private List<String> compilationErrors = new ArrayList<>();
+    private final NonNullList<ItemStack> ITEMS = NonNullList.withSize(DISK_SLOT_COUNT, ItemStack.EMPTY);
 
     public LibraryBlockEntity(BlockPos pos, BlockState state) {
         super(SFMBlockEntities.LIBRARY_BLOCK_ENTITY.get(), pos, state);
     }
 
-    public String getSourceCode() {
-        return sourceCode;
-    }
-
-    public void setSourceCode(String sourceCode) {
-        this.sourceCode = sourceCode;
-        this.cachedDefinitions = null;
-        this.compilationErrors.clear();
-        setChanged();
-        recompile();
-    }
-
-    public List<String> getCompilationErrors() {
-        return compilationErrors;
-    }
-
-    public boolean hasErrors() {
-        return !compilationErrors.isEmpty();
+    /**
+     * Extracts the NAME from SFML source code using regex (fast, avoids full ANTLR parsing).
+     *
+     * @param source The SFML source code
+     * @return The extracted name, or null if not found
+     */
+    public static @Nullable String extractName(String source) {
+        if (source == null || source.isEmpty()) return null;
+        Matcher matcher = NAME_PATTERN.matcher(source);
+        if (matcher.find()) {
+            return matcher.group(1).replace("\\\"", "\"");
+        }
+        return null;
     }
 
     /**
-     * Gets the library definitions, recompiling if necessary.
+     * Gets library entries with their slot indices from inserted disks.
+     * Only returns entries from disks that have a valid NAME statement.
      */
-    public LibraryDefinitions getDefinitions() {
-        if (cachedDefinitions == null) {
-            recompile();
+    public List<LibraryContainerMenu.LibraryEntry> getLibraryEntries() {
+        List<LibraryContainerMenu.LibraryEntry> entries = new ArrayList<>();
+        for (int i = 0; i < DISK_SLOT_COUNT; i++) {
+            ItemStack disk = getItem(i);
+            if (disk.isEmpty() || !(disk.getItem() instanceof DiskItem)) continue;
+
+            String source = DiskItem.getProgramString(disk);
+            String name = extractName(source);
+            if (name != null && !name.isEmpty()) {
+                entries.add(new LibraryContainerMenu.LibraryEntry(name, i));
+            }
         }
-        return cachedDefinitions != null ? cachedDefinitions : LibraryDefinitions.EMPTY;
+        return entries;
     }
 
     /**
-     * Recompiles the source code to extract definitions.
+     * Gets library definitions from a disk with a matching NAME.
+     *
+     * @param libraryName The name to search for
+     * @return The parsed definitions, or null if not found
      */
-    private void recompile() {
-        compilationErrors.clear();
+    public @Nullable LibraryDefinitions getDefinitionsForLibrary(String libraryName) {
+        for (int i = 0; i < DISK_SLOT_COUNT; i++) {
+            ItemStack disk = getItem(i);
+            if (disk.isEmpty() || !(disk.getItem() instanceof DiskItem)) continue;
 
-        if (sourceCode.isEmpty()) {
-            cachedDefinitions = LibraryDefinitions.EMPTY;
-            return;
-        }
+            String source = DiskItem.getProgramString(disk);
+            String name = extractName(source);
 
-        try {
-            // Parse the source code as a library (only protocols, structs, macros)
-            // For now, we'll use a simplified approach - full parsing would need ASTBuilder
-            // This is a placeholder implementation
-            cachedDefinitions = parseLibraryDefinitions(sourceCode);
-        } catch (Exception e) {
-            compilationErrors.add(e.getMessage());
-            cachedDefinitions = null;
+            if (libraryName.equals(name)) {
+                return parseLibraryDefinitions(source);
+            }
         }
+        return null;
     }
 
     /**
      * Parses library definitions from source code.
-     * TODO: Implement actual parsing using ASTBuilder to extract protocols, structs, and macros.
-     * This requires refactoring ASTBuilder to support partial program parsing.
+     * Extracts only protocols, structs, and macros (ignores triggers/let statements).
      */
-    private LibraryDefinitions parseLibraryDefinitions(String source) {
-        // Stub implementation - library block parsing not yet implemented
-        return LibraryDefinitions.EMPTY;
+    public LibraryDefinitions parseLibraryDefinitions(String source) {
+        SFMLLexer lexer = new SFMLLexer(CharStreams.fromString(source));
+        CommonTokenStream tokens = new CommonTokenStream(lexer);
+        SFMLParser parser = new SFMLParser(tokens);
+
+        // Set up error capturing
+        List<String> errors = new ArrayList<>();
+        lexer.removeErrorListeners();
+        parser.removeErrorListeners();
+        Program.ListErrorListener listener = new Program.ListErrorListener(errors);
+        lexer.addErrorListener(listener);
+        parser.addErrorListener(listener);
+
+        SFMLParser.ProgramContext context = parser.program();
+        if (!errors.isEmpty()) {
+            throw new IllegalArgumentException(String.join(", ", errors));
+        }
+
+        // Use ASTBuilder to parse definitions
+        ASTBuilder builder = new ASTBuilder();
+
+        // Parse protocol definitions
+        List<ProtocolDefinition> protocols = new ArrayList<>();
+        for (SFMLParser.ProtocolDefinitionContext protoCtx : context.protocolDefinition()) {
+            protocols.add(builder.visitProtocolDefinition(protoCtx));
+        }
+
+        // Parse struct definitions
+        List<StructDefinition> structs = new ArrayList<>();
+        for (SFMLParser.StructDefinitionContext structCtx : context.structDefinition()) {
+            structs.add(builder.visitStructDefinition(structCtx));
+        }
+
+        // Parse macro definitions
+        List<MacroDefinition> macros = new ArrayList<>();
+        for (SFMLParser.MacroDefinitionContext macroCtx : context.macroDefinition()) {
+            macros.add(builder.visitMacroDefinition(macroCtx));
+        }
+
+        return new LibraryDefinitions(protocols, structs, macros);
     }
 
     @Override
     protected void saveAdditional(CompoundTag tag) {
         super.saveAdditional(tag);
-        tag.putString(NBT_KEY_SOURCE, sourceCode);
+        ContainerHelper.saveAllItems(tag, ITEMS);
     }
 
     @Override
     public void load(CompoundTag tag) {
         super.load(tag);
-        sourceCode = tag.getString(NBT_KEY_SOURCE);
-        cachedDefinitions = null;
+
+        // Backward compatibility: migrate old source code format to disk
+        if (tag.contains("Source")) {
+            String legacySource = tag.getString("Source");
+            if (!legacySource.isEmpty()) {
+                ItemStack disk = new ItemStack(SFMItems.DISK_ITEM.get());
+                DiskItem.setProgram(disk, legacySource);
+                ITEMS.set(0, disk);
+            }
+        } else {
+            ContainerHelper.loadAllItems(tag, ITEMS);
+        }
     }
 
     @Override
-    public Component getDisplayName() {
-        return Component.translatable("container.sfm.library");
+    protected Component getDefaultName() {
+        return LocalizationKeys.LIBRARY_CONTAINER.getComponent();
     }
 
     @Override
-    public @Nullable AbstractContainerMenu createMenu(int containerId, Inventory playerInventory, Player player) {
-        // Library blocks don't have a GUI menu yet - could be added later for editing
-        return null;
+    protected AbstractContainerMenu createMenu(int containerId, Inventory inventory) {
+        return new LibraryContainerMenu(containerId, inventory, this);
+    }
+
+    @Override
+    public int getContainerSize() {
+        return ITEMS.size();
+    }
+
+    @Override
+    public boolean isEmpty() {
+        for (ItemStack item : ITEMS) {
+            if (!item.isEmpty()) return false;
+        }
+        return true;
+    }
+
+    @Override
+    public ItemStack getItem(int slot) {
+        if (slot < 0 || slot >= ITEMS.size()) return ItemStack.EMPTY;
+        return ITEMS.get(slot);
+    }
+
+    @Override
+    public ItemStack removeItem(int slot, int amount) {
+        ItemStack result = ContainerHelper.removeItem(ITEMS, slot, amount);
+        setChanged();
+        return result;
+    }
+
+    @Override
+    public ItemStack removeItemNoUpdate(int slot) {
+        ItemStack result = ContainerHelper.takeItem(ITEMS, slot);
+        setChanged();
+        return result;
+    }
+
+    @Override
+    public void setItem(int slot, ItemStack stack) {
+        if (slot < 0 || slot >= ITEMS.size()) return;
+        ITEMS.set(slot, stack);
+        setChanged();
+    }
+
+    @Override
+    public int getMaxStackSize() {
+        return 1;
+    }
+
+    @Override
+    public boolean canPlaceItem(int slot, ItemStack stack) {
+        return stack.getItem() instanceof DiskItem;
+    }
+
+    @Override
+    public boolean stillValid(Player player) {
+        return SFMContainerUtil.stillValid(this, player);
+    }
+
+    @Override
+    public void clearContent() {
+        ITEMS.clear();
+    }
+
+    // Client-side cache of disk mask for rendering
+    private int clientDiskMask = 0;
+
+    @Override
+    public void setChanged() {
+        super.setChanged();
+        // Sync to client for renderer updates
+        if (level != null && !level.isClientSide()) {
+            level.sendBlockUpdated(worldPosition, getBlockState(), getBlockState(), 3);
+        }
+    }
+
+    // Client sync methods for BlockEntityRenderer
+    @Override
+    public CompoundTag getUpdateTag() {
+        CompoundTag tag = super.getUpdateTag();
+        tag.putInt("DiskMask", computeDiskMask());
+        return tag;
+    }
+
+    @Override
+    public void handleUpdateTag(CompoundTag tag) {
+        super.handleUpdateTag(tag);
+        clientDiskMask = tag.getInt("DiskMask");
+    }
+
+    @Override
+    public Packet<ClientGamePacketListener> getUpdatePacket() {
+        return ClientboundBlockEntityDataPacket.create(this);
+    }
+
+    @Override
+    public void onDataPacket(net.minecraft.network.Connection net, ClientboundBlockEntityDataPacket pkt) {
+        CompoundTag tag = pkt.getTag();
+        if (tag != null) {
+            clientDiskMask = tag.getInt("DiskMask");
+        }
+    }
+
+    /**
+     * Computes a bitmask indicating which slots have disks (server-side).
+     */
+    private int computeDiskMask() {
+        int mask = 0;
+        for (int i = 0; i < ITEMS.size(); i++) {
+            if (!ITEMS.get(i).isEmpty() && ITEMS.get(i).getItem() instanceof DiskItem) {
+                mask |= (1 << i);
+            }
+        }
+        return mask;
+    }
+
+    /**
+     * Returns a bitmask indicating which slots have disks.
+     * Bit 0 = slot 0, bit 1 = slot 1, etc.
+     * Used by the BlockEntityRenderer to show disk indicators.
+     */
+    public int getDiskSlotMask() {
+        if (level != null && level.isClientSide()) {
+            return clientDiskMask;
+        }
+        return computeDiskMask();
     }
 }
diff --git a/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java b/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java
index 3b4e42e8c..f70318373 100644
--- a/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java
+++ b/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java
@@ -1,6 +1,8 @@
 package ca.teamdman.sfm.common.blockentity;
 
 import ca.teamdman.sfm.SFM;
+import ca.teamdman.sfm.common.cablenetwork.CableNetwork;
+import ca.teamdman.sfm.common.cablenetwork.CableNetworkManager;
 import ca.teamdman.sfm.common.config.SFMConfig;
 import ca.teamdman.sfm.common.config.SFMConfigTracker;
 import ca.teamdman.sfm.common.containermenu.ManagerContainerMenu;
@@ -21,6 +23,8 @@
 import ca.teamdman.sfm.common.timing.SFMInstant;
 import ca.teamdman.sfm.common.util.SFMContainerUtil;
 import ca.teamdman.sfml.ast.Program;
+import ca.teamdman.sfml.program_builder.LibraryDefinitions;
+import ca.teamdman.sfml.program_builder.LibraryResolver;
 import com.google.common.base.Joiner;
 import net.minecraft.ChatFormatting;
 import net.minecraft.CrashReportCategory;
@@ -44,6 +48,7 @@
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
+import java.util.Optional;
 import java.util.Set;
 
 public class ManagerBlockEntity extends BaseContainerBlockEntity {
@@ -354,16 +359,71 @@ public void rebuildProgramAndUpdateDisk() {
             this.program = null;
         } else {
             this.incrementRebuildWarningsCooldown();
+            LibraryResolver resolver = createLibraryResolver();
             this.program = DiskItem.compileAndUpdateErrorsAndWarnings(
                     disk,
                     this,
-                    this.shouldRebuildWarnings()
+                    this.shouldRebuildWarnings(),
+                    resolver
             );
         }
         this.configRevision = SFMConfig.SERVER_CONFIG.getRevision();
         sendUpdatePacket();
     }
 
+    /**
+     * Creates a library resolver that scans the cable network for library blocks
+     * containing disks with a matching NAME statement.
+     * The resolver:
+     * 1. Gets all cable positions in the network
+     * 2. For each cable, checks adjacent blocks for LibraryBlockEntity
+     * 3. Extracts the NAME from each disk and compares with the requested library name
+     * 4. Returns the parsed definitions from the first matching disk
+     */
+    public LibraryResolver createLibraryResolver() {
+        return libraryName -> {
+            if (level == null) {
+                return Optional.empty();
+            }
+
+            // Get the cable network for this manager
+            Optional<CableNetwork> networkOpt = CableNetworkManager.getOrRegisterNetworkFromManagerPosition(this);
+            if (networkOpt.isEmpty()) {
+                return Optional.empty();
+            }
+            CableNetwork network = networkOpt.get();
+
+            // Track visited positions to avoid checking the same library block multiple times
+            Set<BlockPos> visited = new java.util.HashSet<>();
+
+            // Scan all positions adjacent to cables for library blocks
+            BlockPos.MutableBlockPos target = new BlockPos.MutableBlockPos();
+            for (BlockPos cablePos : network.getCablePositions().toList()) {
+                for (net.minecraft.core.Direction direction : net.minecraft.core.Direction.values()) {
+                    target.set(cablePos).move(direction);
+                    BlockPos immutableTarget = target.immutable();
+
+                    // Skip if already visited
+                    if (!visited.add(immutableTarget)) {
+                        continue;
+                    }
+
+                    if (!(level.getBlockEntity(immutableTarget) instanceof LibraryBlockEntity library)) {
+                        continue;
+                    }
+
+                    // Check each disk slot in the library block
+                    LibraryDefinitions defs = library.getDefinitionsForLibrary(libraryName);
+                    if (defs != null) {
+                        return Optional.of(defs);
+                    }
+                }
+            }
+
+            return Optional.empty();
+        };
+    }
+
     @Override
     public int getContainerSize() {
 
diff --git a/src/main/java/ca/teamdman/sfm/common/containermenu/LibraryContainerMenu.java b/src/main/java/ca/teamdman/sfm/common/containermenu/LibraryContainerMenu.java
new file mode 100644
index 000000000..ec072ee68
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfm/common/containermenu/LibraryContainerMenu.java
@@ -0,0 +1,238 @@
+package ca.teamdman.sfm.common.containermenu;
+
+import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
+import ca.teamdman.sfm.common.item.DiskItem;
+import ca.teamdman.sfm.common.registry.SFMMenus;
+import net.minecraft.core.BlockPos;
+import net.minecraft.network.FriendlyByteBuf;
+import net.minecraft.world.Container;
+import net.minecraft.world.entity.player.Inventory;
+import net.minecraft.world.entity.player.Player;
+import net.minecraft.world.inventory.AbstractContainerMenu;
+import net.minecraft.world.inventory.Slot;
+import net.minecraft.world.item.ItemStack;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Container menu for the library block GUI.
+ * Provides access to disk slots for storing library disks.
+ */
+public class LibraryContainerMenu extends AbstractContainerMenu {
+
+    /**
+     * Record to track library name and its slot index.
+     */
+    public record LibraryEntry(String name, int slotIndex) {}
+
+    public final Inventory PLAYER_INVENTORY;
+    public final BlockPos LIBRARY_POSITION;
+    public final Container CONTAINER;
+    public List<LibraryEntry> libraryEntries;
+
+    public LibraryContainerMenu(
+            int windowId,
+            Inventory inv,
+            BlockPos blockEntityPos,
+            Container container,
+            List<LibraryEntry> libraryEntries
+    ) {
+        super(SFMMenus.LIBRARY_MENU.get(), windowId);
+        this.PLAYER_INVENTORY = inv;
+        this.LIBRARY_POSITION = blockEntityPos;
+        this.CONTAINER = container;
+        this.libraryEntries = new ArrayList<>(libraryEntries);
+
+        // Add disk slots (2 rows of 5)
+        for (int i = 0; i < LibraryBlockEntity.DISK_SLOT_COUNT; i++) {
+            int x = 44 + (i % 5) * 18;
+            int y = 20 + (i / 5) * 18;
+            this.addSlot(new Slot(container, i, x, y) {
+                @Override
+                public boolean mayPlace(ItemStack stack) {
+                    return stack.getItem() instanceof DiskItem;
+                }
+            });
+        }
+
+        // Add player inventory slots
+        for (int i = 0; i < 3; ++i) {
+            for (int j = 0; j < 9; ++j) {
+                this.addSlot(new Slot(inv, j + i * 9 + 9, 8 + j * 18, 84 + i * 18));
+            }
+        }
+
+        // Add player hotbar slots
+        for (int k = 0; k < 9; ++k) {
+            this.addSlot(new Slot(inv, k, 8 + k * 18, 142));
+        }
+    }
+
+    public LibraryContainerMenu(
+            int windowId,
+            Inventory inventory,
+            FriendlyByteBuf buf
+    ) {
+        this(
+                windowId,
+                inventory,
+                buf.readBlockPos(),
+                new SimpleClientContainer(LibraryBlockEntity.DISK_SLOT_COUNT),
+                readLibraryEntries(buf)
+        );
+    }
+
+    public LibraryContainerMenu(
+            int windowId,
+            Inventory inventory,
+            LibraryBlockEntity library
+    ) {
+        this(
+                windowId,
+                inventory,
+                library.getBlockPos(),
+                library,
+                library.getLibraryEntries()
+        );
+    }
+
+    public static void encode(
+            LibraryBlockEntity library,
+            FriendlyByteBuf buf
+    ) {
+        buf.writeBlockPos(library.getBlockPos());
+        writeLibraryEntries(library.getLibraryEntries(), buf);
+    }
+
+    private static List<LibraryEntry> readLibraryEntries(FriendlyByteBuf buf) {
+        int count = buf.readVarInt();
+        List<LibraryEntry> entries = new ArrayList<>(count);
+        for (int i = 0; i < count; i++) {
+            entries.add(new LibraryEntry(buf.readUtf(256), buf.readVarInt()));
+        }
+        return entries;
+    }
+
+    private static void writeLibraryEntries(List<LibraryEntry> entries, FriendlyByteBuf buf) {
+        buf.writeVarInt(entries.size());
+        for (LibraryEntry entry : entries) {
+            buf.writeUtf(entry.name(), 256);
+            buf.writeVarInt(entry.slotIndex());
+        }
+    }
+
+    @Override
+    public boolean stillValid(Player player) {
+        return player.level.getBlockEntity(LIBRARY_POSITION) instanceof LibraryBlockEntity;
+    }
+
+    @Override
+    public ItemStack quickMoveStack(Player player, int slotIndex) {
+        ItemStack result = ItemStack.EMPTY;
+        Slot slot = this.slots.get(slotIndex);
+
+        if (slot != null && slot.hasItem()) {
+            ItemStack slotStack = slot.getItem();
+            result = slotStack.copy();
+
+            // Disk slots are 0-9, player inventory is 10-45
+            if (slotIndex < LibraryBlockEntity.DISK_SLOT_COUNT) {
+                // Moving from disk slot to player inventory
+                if (!this.moveItemStackTo(slotStack, LibraryBlockEntity.DISK_SLOT_COUNT, this.slots.size(), true)) {
+                    return ItemStack.EMPTY;
+                }
+            } else {
+                // Moving from player inventory to disk slots (only if it's a disk)
+                if (slotStack.getItem() instanceof DiskItem) {
+                    if (!this.moveItemStackTo(slotStack, 0, LibraryBlockEntity.DISK_SLOT_COUNT, false)) {
+                        return ItemStack.EMPTY;
+                    }
+                } else {
+                    return ItemStack.EMPTY;
+                }
+            }
+
+            if (slotStack.isEmpty()) {
+                slot.set(ItemStack.EMPTY);
+            } else {
+                slot.setChanged();
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Simple container for client-side use when the actual block entity isn't available.
+     */
+    private static class SimpleClientContainer implements Container {
+        private final ItemStack[] items;
+
+        public SimpleClientContainer(int size) {
+            this.items = new ItemStack[size];
+            for (int i = 0; i < size; i++) {
+                items[i] = ItemStack.EMPTY;
+            }
+        }
+
+        @Override
+        public int getContainerSize() {
+            return items.length;
+        }
+
+        @Override
+        public boolean isEmpty() {
+            for (ItemStack item : items) {
+                if (!item.isEmpty()) return false;
+            }
+            return true;
+        }
+
+        @Override
+        public ItemStack getItem(int slot) {
+            return slot >= 0 && slot < items.length ? items[slot] : ItemStack.EMPTY;
+        }
+
+        @Override
+        public ItemStack removeItem(int slot, int amount) {
+            if (slot >= 0 && slot < items.length && !items[slot].isEmpty() && amount > 0) {
+                return items[slot].split(amount);
+            }
+            return ItemStack.EMPTY;
+        }
+
+        @Override
+        public ItemStack removeItemNoUpdate(int slot) {
+            if (slot >= 0 && slot < items.length) {
+                ItemStack result = items[slot];
+                items[slot] = ItemStack.EMPTY;
+                return result;
+            }
+            return ItemStack.EMPTY;
+        }
+
+        @Override
+        public void setItem(int slot, ItemStack stack) {
+            if (slot >= 0 && slot < items.length) {
+                items[slot] = stack;
+            }
+        }
+
+        @Override
+        public void setChanged() {
+        }
+
+        @Override
+        public boolean stillValid(Player player) {
+            return true;
+        }
+
+        @Override
+        public void clearContent() {
+            for (int i = 0; i < items.length; i++) {
+                items[i] = ItemStack.EMPTY;
+            }
+        }
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfm/common/item/DiskItem.java b/src/main/java/ca/teamdman/sfm/common/item/DiskItem.java
index e7f1eb814..1fe480dd9 100644
--- a/src/main/java/ca/teamdman/sfm/common/item/DiskItem.java
+++ b/src/main/java/ca/teamdman/sfm/common/item/DiskItem.java
@@ -15,6 +15,7 @@
 import ca.teamdman.sfm.common.util.SFMItemUtils;
 import ca.teamdman.sfm.common.util.SFMTranslationUtils;
 import ca.teamdman.sfml.ast.Program;
+import ca.teamdman.sfml.program_builder.LibraryResolver;
 import ca.teamdman.sfml.program_builder.ProgramBuilder;
 import net.minecraft.ChatFormatting;
 import net.minecraft.nbt.CompoundTag;
@@ -72,6 +73,15 @@ public static void pruneIfDefault(ItemStack stack) {
             ItemStack stack,
             @Nullable ManagerBlockEntity manager,
             boolean updateWarnings
+    ) {
+        return compileAndUpdateErrorsAndWarnings(stack, manager, updateWarnings, LibraryResolver.NONE);
+    }
+
+    public static @Nullable Program compileAndUpdateErrorsAndWarnings(
+            ItemStack stack,
+            @Nullable ManagerBlockEntity manager,
+            boolean updateWarnings,
+            LibraryResolver libraryResolver
     ) {
         if (manager != null) {
             manager.logger.info(x -> x.accept(LocalizationKeys.PROGRAM_COMPILE_FROM_DISK_BEGIN.get()));
@@ -79,7 +89,9 @@ public static void pruneIfDefault(ItemStack stack) {
         AtomicReference<Program> rtn = new AtomicReference<>(null);
         String programString = getProgramString(stack);
 
-        new ProgramBuilder(programString).build()
+        new ProgramBuilder(programString)
+                .withLibraryResolver(libraryResolver)
+                .build()
                 .caseSuccess((successProgram, metadata) -> {
                     if (updateWarnings) {
                         Collection<TranslatableContents> warnings = ProgramLinter.gatherWarnings(
diff --git a/src/main/java/ca/teamdman/sfm/common/localization/LocalizationKeys.java b/src/main/java/ca/teamdman/sfm/common/localization/LocalizationKeys.java
index 97ce78be9..e4a66b44e 100644
--- a/src/main/java/ca/teamdman/sfm/common/localization/LocalizationKeys.java
+++ b/src/main/java/ca/teamdman/sfm/common/localization/LocalizationKeys.java
@@ -492,6 +492,18 @@ public final class LocalizationKeys {
             "program.sfm.warnings.unused_macro",
             "Macro \"%s\" is defined but never expanded."
     );
+    public static final LocalizationEntry PROGRAM_WARNING_UNUSED_LIBRARY = new LocalizationEntry(
+            "program.sfm.warnings.unused_library",
+            "Library \"%s\" is imported but none of its definitions are used."
+    );
+    public static final LocalizationEntry PROGRAM_ERROR_LIBRARY_NOT_FOUND = new LocalizationEntry(
+            "program.sfm.error.library_not_found",
+            "Library \"%s\" not found in cable network."
+    );
+    public static final LocalizationEntry PROGRAM_ERROR_LIBRARY_HAS_ERRORS = new LocalizationEntry(
+            "program.sfm.error.library_has_errors",
+            "Library \"%s\" has compilation errors."
+    );
     public static final LocalizationEntry LIBRARY_CONTAINER = new LocalizationEntry(
             "container.sfm.library",
             "SFML Library"
diff --git a/src/main/java/ca/teamdman/sfm/common/net/ServerboundLibraryDiskSetProgramPacket.java b/src/main/java/ca/teamdman/sfm/common/net/ServerboundLibraryDiskSetProgramPacket.java
new file mode 100644
index 000000000..b5ac6a52d
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfm/common/net/ServerboundLibraryDiskSetProgramPacket.java
@@ -0,0 +1,98 @@
+package ca.teamdman.sfm.common.net;
+
+import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
+import ca.teamdman.sfm.common.containermenu.LibraryContainerMenu;
+import ca.teamdman.sfm.common.item.DiskItem;
+import ca.teamdman.sfml.ast.Program;
+import net.minecraft.core.BlockPos;
+import net.minecraft.network.FriendlyByteBuf;
+import net.minecraft.world.item.ItemStack;
+
+/**
+ * Packet sent from client to server to update a disk's program in a library block slot.
+ */
+public record ServerboundLibraryDiskSetProgramPacket(
+        int containerId,
+        BlockPos libraryPos,
+        int slotIndex,
+        String programString
+) implements SFMPacket {
+
+    public static class Daddy implements SFMPacketDaddy<ServerboundLibraryDiskSetProgramPacket> {
+        @Override
+        public PacketDirection getPacketDirection() {
+            return PacketDirection.SERVERBOUND;
+        }
+
+        @Override
+        public void encode(
+                ServerboundLibraryDiskSetProgramPacket msg,
+                FriendlyByteBuf buf
+        ) {
+            buf.writeVarInt(msg.containerId);
+            buf.writeBlockPos(msg.libraryPos);
+            buf.writeVarInt(msg.slotIndex);
+            buf.writeUtf(msg.programString, Program.MAX_PROGRAM_LENGTH);
+        }
+
+        @Override
+        public ServerboundLibraryDiskSetProgramPacket decode(FriendlyByteBuf buf) {
+            return new ServerboundLibraryDiskSetProgramPacket(
+                    buf.readVarInt(),
+                    buf.readBlockPos(),
+                    buf.readVarInt(),
+                    buf.readUtf(Program.MAX_PROGRAM_LENGTH)
+            );
+        }
+
+        @Override
+        public void handle(
+                ServerboundLibraryDiskSetProgramPacket msg,
+                SFMPacketHandlingContext context
+        ) {
+            var sender = context.sender();
+            if (sender == null) {
+                return;
+            }
+
+            // Verify the player has the menu open
+            if (!(sender.containerMenu instanceof LibraryContainerMenu menu)) {
+                return;
+            }
+            if (menu.containerId != msg.containerId) {
+                return;
+            }
+
+            // Verify the library block exists at the position
+            if (!(sender.level.getBlockEntity(msg.libraryPos) instanceof LibraryBlockEntity library)) {
+                return;
+            }
+
+            // Verify slot index is valid
+            if (msg.slotIndex < 0 || msg.slotIndex >= LibraryBlockEntity.DISK_SLOT_COUNT) {
+                return;
+            }
+
+            // Get the disk in the slot
+            ItemStack disk = library.getItem(msg.slotIndex);
+            if (disk.isEmpty() || !(disk.getItem() instanceof DiskItem)) {
+                return;
+            }
+
+            // Update the disk's program
+            DiskItem.setProgram(disk, msg.programString);
+            DiskItem.compileAndUpdateErrorsAndWarnings(disk, null, true);
+            DiskItem.pruneIfDefault(disk);
+            library.setChanged();
+
+            // Update the menu's library entries
+            menu.libraryEntries.clear();
+            menu.libraryEntries.addAll(library.getLibraryEntries());
+        }
+
+        @Override
+        public Class<ServerboundLibraryDiskSetProgramPacket> getPacketClass() {
+            return ServerboundLibraryDiskSetProgramPacket.class;
+        }
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfm/common/program/linting/MacroUsageLinter.java b/src/main/java/ca/teamdman/sfm/common/program/linting/MacroUsageLinter.java
index 57f840027..3a0b291e3 100644
--- a/src/main/java/ca/teamdman/sfm/common/program/linting/MacroUsageLinter.java
+++ b/src/main/java/ca/teamdman/sfm/common/program/linting/MacroUsageLinter.java
@@ -30,6 +30,11 @@ public void gatherWarnings(
             @Nullable ManagerBlockEntity managerBlockEntity,
             ProblemTracker tracker
     ) {
+        // Skip for library disks (no triggers = definitions are meant to be exported)
+        if (program.triggers().isEmpty()) {
+            return;
+        }
+
         // Collect all macro names that are used in expand statements
         Set<String> usedMacros = new HashSet<>();
         collectUsedMacros(program, usedMacros);
diff --git a/src/main/java/ca/teamdman/sfm/common/program/linting/ProtocolUsageLinter.java b/src/main/java/ca/teamdman/sfm/common/program/linting/ProtocolUsageLinter.java
index c72f14b51..8f9c35125 100644
--- a/src/main/java/ca/teamdman/sfm/common/program/linting/ProtocolUsageLinter.java
+++ b/src/main/java/ca/teamdman/sfm/common/program/linting/ProtocolUsageLinter.java
@@ -30,6 +30,11 @@ public void gatherWarnings(
             @Nullable ManagerBlockEntity managerBlockEntity,
             ProblemTracker tracker
     ) {
+        // Skip for library disks (no triggers = definitions are meant to be exported)
+        if (program.triggers().isEmpty()) {
+            return;
+        }
+
         // Collect all protocols that are referenced
         Set<String> usedProtocols = new HashSet<>();
 
diff --git a/src/main/java/ca/teamdman/sfm/common/program/linting/StructDefinitionLinter.java b/src/main/java/ca/teamdman/sfm/common/program/linting/StructDefinitionLinter.java
index 4a54db946..a36a26060 100644
--- a/src/main/java/ca/teamdman/sfm/common/program/linting/StructDefinitionLinter.java
+++ b/src/main/java/ca/teamdman/sfm/common/program/linting/StructDefinitionLinter.java
@@ -25,6 +25,11 @@ public void gatherWarnings(
             @Nullable ManagerBlockEntity managerBlockEntity,
             ProblemTracker tracker
     ) {
+        // Skip for library disks (no triggers = definitions are meant to be exported)
+        if (program.triggers().isEmpty()) {
+            return;
+        }
+
         // Collect all struct names that are instantiated
         Set<String> usedStructs = new HashSet<>();
         for (LetStatement letStatement : program.letStatements()) {
diff --git a/src/main/java/ca/teamdman/sfm/common/registry/SFMMenus.java b/src/main/java/ca/teamdman/sfm/common/registry/SFMMenus.java
index 0fb6d050f..1062420af 100644
--- a/src/main/java/ca/teamdman/sfm/common/registry/SFMMenus.java
+++ b/src/main/java/ca/teamdman/sfm/common/registry/SFMMenus.java
@@ -3,8 +3,10 @@
 
 import ca.teamdman.sfm.SFM;
 import ca.teamdman.sfm.client.ClientRayCastHelpers;
+import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
 import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
 import ca.teamdman.sfm.common.blockentity.TestBarrelTankBlockEntity;
+import ca.teamdman.sfm.common.containermenu.LibraryContainerMenu;
 import ca.teamdman.sfm.common.containermenu.ManagerContainerMenu;
 import ca.teamdman.sfm.common.containermenu.TestBarrelTankContainerMenu;
 import ca.teamdman.sfm.common.util.SFMEnvironmentUtils;
@@ -103,6 +105,44 @@ public TestBarrelTankContainerMenu create(
                     })
     );
 
+    public static final SFMRegistryObject<MenuType<?>, MenuType<LibraryContainerMenu>> LIBRARY_MENU = MENU_TYPES.register(
+            "library",
+            () -> IForgeMenuType.create(
+                    new IContainerFactory<>() {
+                        @Override
+                        public LibraryContainerMenu create(
+                                int windowId,
+                                Inventory inv,
+                                FriendlyByteBuf data
+                        ) {
+                            return new LibraryContainerMenu(
+                                    windowId,
+                                    inv,
+                                    data
+                            );
+                        }
+
+                        @Override
+                        public LibraryContainerMenu create(
+                                int windowId,
+                                Inventory inv
+                        ) {
+                            if (SFMEnvironmentUtils.isClient()) {
+                                BlockEntity be = ClientRayCastHelpers.getLookBlockEntity();
+                                if (!(be instanceof LibraryBlockEntity blockEntity)) {
+                                    return IContainerFactory.super.create(windowId, inv);
+                                }
+                                return new LibraryContainerMenu(windowId, inv, blockEntity);
+                            } else {
+                                return IContainerFactory.super.create(
+                                        windowId,
+                                        inv
+                                );
+                            }
+                        }
+                    })
+    );
+
     public static void register(IEventBus bus) {
 
         MENU_TYPES.register(bus);
diff --git a/src/main/java/ca/teamdman/sfm/common/registry/SFMPackets.java b/src/main/java/ca/teamdman/sfm/common/registry/SFMPackets.java
index 1f9d08cb6..4eb3621d2 100644
--- a/src/main/java/ca/teamdman/sfm/common/registry/SFMPackets.java
+++ b/src/main/java/ca/teamdman/sfm/common/registry/SFMPackets.java
@@ -60,6 +60,7 @@ public static void register() {
         registerPacket(new ServerboundLabelGunSetActiveLabelPacket.Daddy());
         registerPacket(new ServerboundLabelGunUsePacket.Daddy());
         registerPacket(new ServerboundLabelInspectionRequestPacket.Daddy());
+        registerPacket(new ServerboundLibraryDiskSetProgramPacket.Daddy());
         registerPacket(new ServerboundManagerClearLogsPacket.Daddy());
         registerPacket(new ServerboundManagerFixPacket.Daddy());
         registerPacket(new ServerboundManagerLogDesireUpdatePacket.Daddy());
diff --git a/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java b/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
index edee1c669..73ebf821d 100644
--- a/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
+++ b/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
@@ -3,6 +3,8 @@
 import ca.teamdman.langs.SFMLBaseVisitor;
 import ca.teamdman.langs.SFMLParser;
 import ca.teamdman.sfm.common.config.SFMConfig;
+import ca.teamdman.sfml.program_builder.LibraryDefinitions;
+import ca.teamdman.sfml.program_builder.LibraryResolver;
 import com.mojang.datafixers.util.Pair;
 import org.antlr.v4.runtime.ParserRuleContext;
 import org.antlr.v4.runtime.tree.ParseTree;
@@ -36,6 +38,16 @@ public class ASTBuilder extends SFMLBaseVisitor<ASTNode> {
     /// Macro definitions indexed by name, populated during AST building
     private final Map<String, MacroDefinition> MACRO_DEFINITIONS = new HashMap<>();
 
+    /// Library resolver for resolving "use library" statements
+    private LibraryResolver libraryResolver = LibraryResolver.NONE;
+
+    /**
+     * Sets the library resolver used to resolve "use library" statements.
+     */
+    public void setLibraryResolver(LibraryResolver resolver) {
+        this.libraryResolver = resolver != null ? resolver : LibraryResolver.NONE;
+    }
+
     /// @return hierarchy of nodes; e.g., Program > Trigger > Block > IOStatement > LabelAccess > Label
     public List<Pair<ASTNode, ParserRuleContext>> getNodesUnderCursor(int cursorPos) {
 
@@ -208,7 +220,40 @@ public Program visitProgram(SFMLParser.ProgramContext ctx) {
                 .map(this::visitLibrary)
                 .collect(Collectors.toList());
 
-        // Process protocol definitions
+        // Resolve library definitions and import them before processing local definitions
+        for (LibraryStatement libraryStmt : libraries) {
+            Optional<LibraryDefinitions> resolved = libraryResolver.resolve(libraryStmt.blockLabel());
+            if (resolved.isEmpty()) {
+                throw new IllegalArgumentException("Library '" + libraryStmt.blockLabel() + "' not found in cable network");
+            }
+            LibraryDefinitions libDefs = resolved.get();
+
+            // Import protocols from library
+            for (ProtocolDefinition proto : libDefs.protocols()) {
+                if (PROTOCOL_DEFINITIONS.containsKey(proto.name())) {
+                    throw new IllegalArgumentException("Duplicate protocol definition: " + proto.name() + " (imported from library '" + libraryStmt.blockLabel() + "')");
+                }
+                PROTOCOL_DEFINITIONS.put(proto.name(), proto);
+            }
+
+            // Import structs from library
+            for (StructDefinition struct : libDefs.structs()) {
+                if (STRUCT_DEFINITIONS.containsKey(struct.name())) {
+                    throw new IllegalArgumentException("Duplicate struct definition: " + struct.name() + " (imported from library '" + libraryStmt.blockLabel() + "')");
+                }
+                STRUCT_DEFINITIONS.put(struct.name(), struct);
+            }
+
+            // Import macros from library
+            for (MacroDefinition macro : libDefs.macros()) {
+                if (MACRO_DEFINITIONS.containsKey(macro.name())) {
+                    throw new IllegalArgumentException("Duplicate macro definition: " + macro.name() + " (imported from library '" + libraryStmt.blockLabel() + "')");
+                }
+                MACRO_DEFINITIONS.put(macro.name(), macro);
+            }
+        }
+
+        // Process protocol definitions (local definitions can override or extend library ones)
         var protocolDefinitions = ctx
                 .protocolDefinition()
                 .stream()
diff --git a/src/main/java/ca/teamdman/sfml/program_builder/ProgramBuilder.java b/src/main/java/ca/teamdman/sfml/program_builder/ProgramBuilder.java
index 4d5645a32..70f206671 100644
--- a/src/main/java/ca/teamdman/sfml/program_builder/ProgramBuilder.java
+++ b/src/main/java/ca/teamdman/sfml/program_builder/ProgramBuilder.java
@@ -35,6 +35,9 @@ public class ProgramBuilder {
     /// Indicates that the resulting program may be mutated in naughty ways that we don't want interfering with our cache.
     private boolean useCache = true;
 
+    /// Library resolver for resolving "use library" statements
+    private LibraryResolver libraryResolver = LibraryResolver.NONE;
+
     public ProgramBuilder(@Nullable String programString) {
 
         if (programString == null) {
@@ -43,6 +46,16 @@ public ProgramBuilder(@Nullable String programString) {
         this.programString = programString;
     }
 
+    /// Sets the library resolver used to resolve "use library" statements.
+    public ProgramBuilder withLibraryResolver(LibraryResolver resolver) {
+        this.libraryResolver = resolver != null ? resolver : LibraryResolver.NONE;
+        // Using a library resolver requires disabling cache since different resolvers may give different results
+        if (resolver != LibraryResolver.NONE) {
+            this.useCache = false;
+        }
+        return this;
+    }
+
     /// Checks if the program object is stored in the cache.
     /// If so, mutating the program object is a disallowed behaviour.
     public static boolean isMutationAllowed(Program program) {
@@ -76,6 +89,7 @@ public ProgramBuildResult build(
         CommonTokenStream tokens = new CommonTokenStream(lexer);
         SFMLParser parser = new SFMLParser(tokens);
         ASTBuilder builder = new ASTBuilder();
+        builder.setLibraryResolver(libraryResolver);
 
         // set up error capturing
         lexer.removeErrorListeners();
diff --git a/src/main/resources/assets/sfm/textures/block/library_back.png b/src/main/resources/assets/sfm/textures/block/library_back.png
new file mode 100644
index 0000000000000000000000000000000000000000..9d6cb864c55911d9bed961f9f58bd9d934b48658
GIT binary patch
literal 119
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`cAhSdAr*1S8@3w#_Sc&>N#OT+
zhNKr+D<`%F@-P&798^BY5GSW6(xYcD#G}yCzL@bz!UjeI;fv051=?ORGdOIIwA9>h
Rzz;Nu!PC{xWt~$(698$MBL@Hg

literal 0
HcmV?d00001

diff --git a/src/main/resources/assets/sfm/textures/block/library_bot.png b/src/main/resources/assets/sfm/textures/block/library_bot.png
new file mode 100644
index 0000000000000000000000000000000000000000..5893c3c2d147485a5bd47e14529f35ba4e566eba
GIT binary patch
literal 158
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`sh%#5Ar)~;&l++y7znsrys~I*
z2m1zr99@?8^=mxd2>oBMS<HU&tK3=34c)E#ZI^$#c}+Ehb<3}44xZZYm4XFM4SFkG
z4{$Q>S|Y}%&hlbX6w4fe1>RW@iCTt<c?)dncQO398F71F-IK>a3mH6J{an^LB{Ts5
DrhYjS

literal 0
HcmV?d00001

diff --git a/src/main/resources/assets/sfm/textures/block/library_front.png b/src/main/resources/assets/sfm/textures/block/library_front.png
new file mode 100644
index 0000000000000000000000000000000000000000..b2fa63c0b060eb5d0d40587db2eb07fd990ef536
GIT binary patch
literal 140
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`!JaOTAr*1S8@3w#_Sc&>N#OT+
zhNKr+D<`%F@-P&79E{+7@bsY)7k?77$3Y3U3C$~CGYPOivv)Fi%cH=WY|3y~Eyg65
nM}fVWw_zrS(OeOp%j^t+_rp%dtBFYfjc4$5^>bP0l+XkK<FqOb

literal 0
HcmV?d00001

diff --git a/src/main/resources/assets/sfm/textures/block/library_side.png b/src/main/resources/assets/sfm/textures/block/library_side.png
new file mode 100644
index 0000000000000000000000000000000000000000..bb87c528a8ce8481a0c8dac1ed04bdca8ec6ba90
GIT binary patch
literal 148
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`(Vi}jAr*1S8@3w#_Sc&>N#OT+
zhNKr+D<`%F@-P&79Nc2uFuk2yUoC@Sqr`H?7iNo+o7e=p3#A(Jl&#PN*%vZCN!Y+>
iAbgRzTcGVFGsCygu$Lm7(cD057(8A5T-G@yGywpEDK2jS

literal 0
HcmV?d00001

diff --git a/src/main/resources/assets/sfm/textures/block/library_top.png b/src/main/resources/assets/sfm/textures/block/library_top.png
new file mode 100644
index 0000000000000000000000000000000000000000..e1afbeb72b267ee1829ebe73ef7bcdd031d8b0a7
GIT binary patch
literal 160
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`>7Fi*Ar*1S8@3w#_Sc&>N#OT+
zhNKr+D<`%F@?>}fFeFb<(B~JINKQU{CGb9jK)Xm!BEv4<mK#^h8SZwr7_>3&$T@U$
z**?Y>ekv`7JO@&R^~~BBMbuSNm_H=WVVlr=kZr+j2Q4;+iwy~vKC$t01FdB6boFyt
I=akR{08Z95C;$Ke

literal 0
HcmV?d00001

diff --git a/src/main/resources/assets/sfm/textures/gui/container/library.png b/src/main/resources/assets/sfm/textures/gui/container/library.png
new file mode 100644
index 0000000000000000000000000000000000000000..e2440b09cda96920637a8a32963e85c44299bc9f
GIT binary patch
literal 1728
zcmeAS@N?(olHy`uVBq!ia0y~yU<5K5893O0R7}x|GzJE?c25__kczmscQ<w|4Ham;
z$T`QwMD!yg4@)rf!SD5JCi1a$*{`sUEoWcOmwj-0*oWd9m%p(5eY(H?|4+5tH~shP
ze}8NJUQ=^o|NmdXQPUYYe%LX{%Lm_@#K^Id`9n;^%OgAv6BsXSqa}G^8{>~(Uzcw$
zUjF{)S^v`vEV(ib@%2A{uD$cJy6*F3BL+vdgnMVp{mwD4NH$cO-?y}67D!=ucDLsF
z6OglJlz*N(*_cj>fNq_@;{bB;5Ak<*;SQ8$fACZJbvoP!1MW^lu-s;I0EM8#?IA&~
zXM6B?{n>r9t!v+XvAw^9k>l4y#)^MGUz~sDH{ZJUym=-=6VCyg@?Vq6v)B|)Fq|n~
zu3x!4ZSV-bxXR$MJe8p-j`zUvru}H%@c4G~&Pz}lQR4-r+vk4qpZv~(6ZN|<s_(CW
z6Z7B@+$+WKatkn>uV(xa@u9qU`T4o~p3gR6aI`mKI4^(F4&g5&hR=6idf!_q*`UB|
z095s4?kq-*!6LXIoLOP+G?064VI`|f8RYjLtu-(I1<c6%JedW)C^LWflRtB)B{rUh
zZNMalOul09h&EzSywC0c@_B{c>MbjuSA%K|nt+D8|JdUfE6#Arbu<TA;OXk;vd$@?
F2>`D(vd#bi

literal 0
HcmV?d00001


From abf34fe962192c4e77884c837be7f8918436f157 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 01:37:02 +0100
Subject: [PATCH 14/33] refactor: remove unused import feature and add
 templates

---
 src/main/antlr/sfml/SFML.g4                   | 10 ++---
 .../ProgramSyntaxHighlightingHelper.java      |  1 -
 .../java/ca/teamdman/sfml/ast/ASTBuilder.java | 17 +-------
 .../ca/teamdman/sfml/ast/ImportStatement.java | 15 -------
 .../java/ca/teamdman/sfml/ast/Program.java    |  8 +---
 .../sfml/program_builder/ImportResolver.java  | 24 -----------
 .../sfm/template_programs/library_blocks.sfml | 33 +++++++++++++++
 .../protocols_and_macros.sfml                 | 42 +++++++++++++++++++
 .../assets/sfm/template_programs/structs.sfml | 29 +++++++++++++
 src/test/java/ca/teamdman/sfml/SFMLTests.java | 37 +++++-----------
 10 files changed, 121 insertions(+), 95 deletions(-)
 delete mode 100644 src/main/java/ca/teamdman/sfml/ast/ImportStatement.java
 delete mode 100644 src/main/java/ca/teamdman/sfml/program_builder/ImportResolver.java
 create mode 100644 src/main/resources/assets/sfm/template_programs/library_blocks.sfml
 create mode 100644 src/main/resources/assets/sfm/template_programs/protocols_and_macros.sfml
 create mode 100644 src/main/resources/assets/sfm/template_programs/structs.sfml

diff --git a/src/main/antlr/sfml/SFML.g4 b/src/main/antlr/sfml/SFML.g4
index c660060c8..7be16c254 100644
--- a/src/main/antlr/sfml/SFML.g4
+++ b/src/main/antlr/sfml/SFML.g4
@@ -6,13 +6,12 @@ package ca.teamdman.langs;
     public boolean INCLUDE_UNUSED = false; // we want syntax highlighting to not break on unexpected tokens
 }
 
-program : name? import_* library* protocolDefinition* structDefinition* macroDefinition* letStatement* trigger* EOF;
+program : name? library* protocolDefinition* structDefinition* macroDefinition* letStatement* trigger* EOF;
 
 //
-// IMPORTS AND LIBRARIES
+// LIBRARIES
 //
 
-import_ : IMPORT string ;
 library : USE LIBRARY string ;
 
 //
@@ -219,7 +218,7 @@ label           : (identifier)  #RawLabel
 
 emptyslots      : EMPTY (SLOTS | SLOT) IN ;
 
-identifier : (IDENTIFIER | REDSTONE | GLOBAL | SECOND | SECONDS | TOP | BOTTOM | LEFT | RIGHT | FRONT | BACK | INPUT | OUTPUT | LABEL | STRUCT | LET | USING | SLOT | SLOTS | SIDE | BLOCK | PROTOCOL | MACRO | EXPAND | IMPORT | USE | LIBRARY | RESOURCE | SIDEQUALIFIER | SLOTQUALIFIER | NUMBERTYPE) ;
+identifier : (IDENTIFIER | REDSTONE | GLOBAL | SECOND | SECONDS | TOP | BOTTOM | LEFT | RIGHT | FRONT | BACK | INPUT | OUTPUT | LABEL | STRUCT | LET | USING | SLOT | SLOTS | SIDE | BLOCK | PROTOCOL | MACRO | EXPAND | USE | LIBRARY | RESOURCE | SIDEQUALIFIER | SLOTQUALIFIER | NUMBERTYPE) ;
 
 // GENERAL
 string: STRING ;
@@ -339,8 +338,7 @@ NUMBERTYPE      : N U M B E R ;
 MACRO           : M A C R O ;
 EXPAND          : E X P A N D ;
 
-// IMPORT SYMBOLS
-IMPORT          : I M P O R T ;
+// LIBRARY SYMBOLS
 USE             : U S E ;
 LIBRARY         : L I B R A R Y ;
 
diff --git a/src/main/java/ca/teamdman/sfm/client/text_styling/ProgramSyntaxHighlightingHelper.java b/src/main/java/ca/teamdman/sfm/client/text_styling/ProgramSyntaxHighlightingHelper.java
index 7f026fed7..8623e6e34 100644
--- a/src/main/java/ca/teamdman/sfm/client/text_styling/ProgramSyntaxHighlightingHelper.java
+++ b/src/main/java/ca/teamdman/sfm/client/text_styling/ProgramSyntaxHighlightingHelper.java
@@ -163,7 +163,6 @@ private static ChatFormatting getColour(Token token) {
             case SFMLLexer.USING:
             case SFMLLexer.MACRO:
             case SFMLLexer.EXPAND:
-            case SFMLLexer.IMPORT:
             case SFMLLexer.USE:
             case SFMLLexer.LIBRARY:
                 return ChatFormatting.BLUE;
diff --git a/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java b/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
index 73ebf821d..7350cb5b9 100644
--- a/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
+++ b/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
@@ -206,13 +206,6 @@ public Program visitProgram(SFMLParser.ProgramContext ctx) {
         }
         var name = visitName(ctx.name());
 
-        // Process imports
-        var imports = ctx
-                .import_()
-                .stream()
-                .map(this::visitImport_)
-                .collect(Collectors.toList());
-
         // Process library references
         var libraries = ctx
                 .library()
@@ -296,7 +289,6 @@ public Program visitProgram(SFMLParser.ProgramContext ctx) {
         Program program = new Program(
                 this,
                 name.value(),
-                imports,
                 libraries,
                 protocolDefinitions,
                 structDefinitions,
@@ -310,14 +302,7 @@ public Program visitProgram(SFMLParser.ProgramContext ctx) {
         return program;
     }
 
-    // ===== IMPORTS AND LIBRARIES =====
-
-    public ImportStatement visitImport_(SFMLParser.Import_Context ctx) {
-        String path = visitString(ctx.string()).value();
-        ImportStatement importStmt = new ImportStatement(path);
-        trackNode(importStmt, ctx);
-        return importStmt;
-    }
+    // ===== LIBRARIES =====
 
     public LibraryStatement visitLibrary(SFMLParser.LibraryContext ctx) {
         String blockLabel = visitString(ctx.string()).value();
diff --git a/src/main/java/ca/teamdman/sfml/ast/ImportStatement.java b/src/main/java/ca/teamdman/sfml/ast/ImportStatement.java
deleted file mode 100644
index db7be02a2..000000000
--- a/src/main/java/ca/teamdman/sfml/ast/ImportStatement.java
+++ /dev/null
@@ -1,15 +0,0 @@
-package ca.teamdman.sfml.ast;
-
-/**
- * Represents an import statement for file imports.
- * Example: import "machines.sfml"
- */
-public record ImportStatement(
-        String path
-) implements ASTNode {
-
-    @Override
-    public String toString() {
-        return "import \"" + path + "\"";
-    }
-}
diff --git a/src/main/java/ca/teamdman/sfml/ast/Program.java b/src/main/java/ca/teamdman/sfml/ast/Program.java
index e63b4a0d3..9f7c0ce42 100644
--- a/src/main/java/ca/teamdman/sfml/ast/Program.java
+++ b/src/main/java/ca/teamdman/sfml/ast/Program.java
@@ -34,8 +34,6 @@ public record Program(
 
         String name,
 
-        List<ImportStatement> imports,
-
         List<LibraryStatement> libraries,
 
         List<ProtocolDefinition> protocolDefinitions,
@@ -54,7 +52,7 @@ public record Program(
 ) implements Statement {
 
     /**
-     * Backward-compatible constructor for programs without protocols, macros, imports, or libraries.
+     * Backward-compatible constructor for programs without protocols, macros, or libraries.
      */
     public Program(
             ASTBuilder astBuilder,
@@ -70,7 +68,6 @@ public Program(
                 name,
                 List.of(),
                 List.of(),
-                List.of(),
                 structDefinitions,
                 List.of(),
                 letStatements,
@@ -249,9 +246,6 @@ public String toString() {
 
         var rtn = new StringBuilder();
         rtn.append("NAME \"").append(name).append("\"\n");
-        for (ImportStatement importStmt : imports) {
-            rtn.append(importStmt).append("\n");
-        }
         for (LibraryStatement libraryStmt : libraries) {
             rtn.append(libraryStmt).append("\n");
         }
diff --git a/src/main/java/ca/teamdman/sfml/program_builder/ImportResolver.java b/src/main/java/ca/teamdman/sfml/program_builder/ImportResolver.java
deleted file mode 100644
index eba2957e1..000000000
--- a/src/main/java/ca/teamdman/sfml/program_builder/ImportResolver.java
+++ /dev/null
@@ -1,24 +0,0 @@
-package ca.teamdman.sfml.program_builder;
-
-import java.util.Optional;
-
-/**
- * Interface for resolving file imports in SFML programs.
- * Implementations can resolve imports from the filesystem, resources, or other sources.
- */
-@FunctionalInterface
-public interface ImportResolver {
-
-    /**
-     * Resolves an import path to its SFML source code.
-     *
-     * @param path the import path (e.g., "machines.sfml")
-     * @return the SFML source code, or empty if not found
-     */
-    Optional<String> resolve(String path);
-
-    /**
-     * A resolver that always fails to find imports.
-     */
-    ImportResolver NONE = path -> Optional.empty();
-}
diff --git a/src/main/resources/assets/sfm/template_programs/library_blocks.sfml b/src/main/resources/assets/sfm/template_programs/library_blocks.sfml
new file mode 100644
index 000000000..558562755
--- /dev/null
+++ b/src/main/resources/assets/sfm/template_programs/library_blocks.sfml
@@ -0,0 +1,33 @@
+NAME "Library Blocks"
+
+-- Library blocks let you share definitions across programs
+-- Place a Library block, insert a disk with definitions, and label it
+
+-- A library disk might contain:
+--   protocol Smeltable
+--       input: sidequalifier slotqualifier
+--       output: sidequalifier slotqualifier
+--   end
+--
+--   struct Furnace : Smeltable
+--       input: TOP SIDE SLOTS 0
+--       output: BOTTOM SIDE SLOTS 2
+--   end
+--
+--   macro smelt(m: Smeltable, src, dst)
+--       input from src
+--       output to m using input
+--   end
+
+-- Then in your program, use:
+-- use library "factory_defs"
+
+-- Now you can use Smeltable, Furnace, and smelt macro
+-- as if they were defined in this file!
+
+-- let f = Furnace { label: "my_furnace" }
+-- every 20 ticks do
+--     expand smelt(f, ores, ingots)
+-- end
+
+-- Note: Library blocks need to exist in-world with a disk containing definitions
diff --git a/src/main/resources/assets/sfm/template_programs/protocols_and_macros.sfml b/src/main/resources/assets/sfm/template_programs/protocols_and_macros.sfml
new file mode 100644
index 000000000..a0b3a1991
--- /dev/null
+++ b/src/main/resources/assets/sfm/template_programs/protocols_and_macros.sfml
@@ -0,0 +1,42 @@
+NAME "Protocols and Macros"
+
+-- Protocols define interfaces that structs can implement
+-- This ensures consistent field names and types
+
+protocol Smeltable
+    input: sidequalifier slotqualifier
+    fuel: sidequalifier slotqualifier
+    output: sidequalifier slotqualifier
+end
+
+-- Structs implement protocols using ":"
+struct Furnace : Smeltable
+    input: TOP SIDE SLOTS 0
+    fuel: BOTTOM SIDE SLOTS 1
+    output: BOTTOM SIDE SLOTS 2
+end
+
+struct BlastFurnace : Smeltable
+    input: TOP SIDE SLOTS 0
+    fuel: BOTTOM SIDE SLOTS 1
+    output: BOTTOM SIDE SLOTS 2
+end
+
+-- Macros are reusable code templates
+-- Parameters can be constrained to protocols
+macro smelt(machine: Smeltable, source, dest)
+    input from source
+    output to machine using input
+    forget
+    input from machine using output
+    output to dest
+end
+
+let furnace = Furnace { label: "furnaces" }
+let blast = BlastFurnace { label: "blast_furnaces" }
+
+-- Use "expand" to invoke macros
+every 20 ticks do
+    expand smelt(furnace, ore_chest, ingot_chest)
+    expand smelt(blast, iron_ore, iron_ingots)
+end
diff --git a/src/main/resources/assets/sfm/template_programs/structs.sfml b/src/main/resources/assets/sfm/template_programs/structs.sfml
new file mode 100644
index 000000000..ffe0fe00b
--- /dev/null
+++ b/src/main/resources/assets/sfm/template_programs/structs.sfml
@@ -0,0 +1,29 @@
+NAME "Structs"
+
+-- Structs let you define reusable configurations for blocks
+-- Each struct field can hold sides, slots, labels, numbers, or resources
+
+struct Furnace
+    input: TOP SIDE SLOTS 0
+    fuel: BOTTOM SIDE SLOTS 1
+    output: BOTTOM SIDE SLOTS 2
+end
+
+-- Create an instance bound to blocks labelled "furnaces"
+let smelter = Furnace { label: "furnaces" }
+
+-- Use the "using" keyword to access struct fields
+every 20 ticks do
+    input from ore_chest
+    output to smelter using input
+
+    forget
+
+    input from fuel_chest
+    output retain 1 to each smelter using fuel
+
+    forget
+
+    input from smelter using output
+    output to results
+end
diff --git a/src/test/java/ca/teamdman/sfml/SFMLTests.java b/src/test/java/ca/teamdman/sfml/SFMLTests.java
index 5fb76027f..e68f15091 100644
--- a/src/test/java/ca/teamdman/sfml/SFMLTests.java
+++ b/src/test/java/ca/teamdman/sfml/SFMLTests.java
@@ -1397,28 +1397,12 @@ expand transfer(chest_a, chest_b)
         assertTrue(expandStmt.expandedStatements().get(1) instanceof ca.teamdman.sfml.ast.OutputStatement);
     }
 
-    // ===== IMPORT AND LIBRARY TESTS =====
-
-    @Test
-    public void importStatement() {
-        // Import statements parse correctly (resolution happens at build time)
-        assertNoCompileErrors(
-                """
-                        NAME "Import Test"
-
-                        import "machines.sfml"
-
-                        every 20 ticks do
-                            input from chest
-                        end
-                        """
-        );
-    }
+    // ===== LIBRARY TESTS =====
 
     @Test
     public void libraryStatement() {
-        // Library statements parse correctly (resolution happens at build time)
-        assertNoCompileErrors(
+        // Library statements parse correctly but resolution fails without in-game library blocks
+        assertCompileErrorsPresent(
                 """
                         NAME "Library Test"
 
@@ -1427,25 +1411,26 @@ public void libraryStatement() {
                         every 20 ticks do
                             input from chest
                         end
-                        """
+                        """,
+                new IllegalArgumentException("Library 'factory_config' not found in cable network")
         );
     }
 
     @Test
-    public void multipleImportsAndLibraries() {
-        assertNoCompileErrors(
+    public void multipleLibraries() {
+        // Library statements parse correctly but resolution fails without in-game library blocks
+        assertCompileErrorsPresent(
                 """
-                        NAME "Multiple Imports Test"
+                        NAME "Multiple Libraries Test"
 
-                        import "machines.sfml"
-                        import "protocols.sfml"
                         use library "factory_config"
                         use library "shared_macros"
 
                         every 20 ticks do
                             input from chest
                         end
-                        """
+                        """,
+                new IllegalArgumentException("Library 'factory_config' not found in cable network")
         );
     }
 

From a314d635ddfa5ea917ae6f73bb24e7ad9bdf15d0 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 01:39:36 +0100
Subject: [PATCH 15/33] perf: optimize library block resolution with auto-label
 cache

---
 .../blockentity/LibraryBlockEntity.java       |  6 +++
 .../blockentity/ManagerBlockEntity.java       | 43 ++++++----------
 .../sfm/common/cablenetwork/CableNetwork.java | 49 +++++++++++++++++++
 3 files changed, 71 insertions(+), 27 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
index c143ed6bc..64f72e67e 100644
--- a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
+++ b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
@@ -44,6 +44,12 @@
  */
 public class LibraryBlockEntity extends BaseContainerBlockEntity {
 
+    /**
+     * Reserved label used to identify library blocks in the cable network.
+     * This label is auto-registered when the network discovers adjacent library blocks.
+     */
+    public static final String LIBRARY_LABEL = "sfm:library";
+
     public static final int DISK_SLOT_COUNT = 10;
 
     /**
diff --git a/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java b/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java
index f70318373..36358f62f 100644
--- a/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java
+++ b/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java
@@ -372,12 +372,12 @@ public void rebuildProgramAndUpdateDisk() {
     }
 
     /**
-     * Creates a library resolver that scans the cable network for library blocks
-     * containing disks with a matching NAME statement.
+     * Creates a library resolver that finds definitions from library blocks on the cable network.
+     * Uses the auto-discovered label cache for O(1) library block lookup.
      * The resolver:
-     * 1. Gets all cable positions in the network
-     * 2. For each cable, checks adjacent blocks for LibraryBlockEntity
-     * 3. Extracts the NAME from each disk and compares with the requested library name
+     * 1. Gets the cable network connected to this manager
+     * 2. Uses the auto-label cache to get all library block positions
+     * 3. For each library block, checks disk slots for a matching NAME
      * 4. Returns the parsed definitions from the first matching disk
      */
     public LibraryResolver createLibraryResolver() {
@@ -393,30 +393,19 @@ public LibraryResolver createLibraryResolver() {
             }
             CableNetwork network = networkOpt.get();
 
-            // Track visited positions to avoid checking the same library block multiple times
-            Set<BlockPos> visited = new java.util.HashSet<>();
+            // O(1) lookup for all library positions via auto-discovered labels
+            Set<BlockPos> libraryPositions = network.getOrRebuildAutoLabels()
+                    .getPositions(LibraryBlockEntity.LIBRARY_LABEL);
 
-            // Scan all positions adjacent to cables for library blocks
-            BlockPos.MutableBlockPos target = new BlockPos.MutableBlockPos();
-            for (BlockPos cablePos : network.getCablePositions().toList()) {
-                for (net.minecraft.core.Direction direction : net.minecraft.core.Direction.values()) {
-                    target.set(cablePos).move(direction);
-                    BlockPos immutableTarget = target.immutable();
-
-                    // Skip if already visited
-                    if (!visited.add(immutableTarget)) {
-                        continue;
-                    }
-
-                    if (!(level.getBlockEntity(immutableTarget) instanceof LibraryBlockEntity library)) {
-                        continue;
-                    }
+            // O(N) scan of libraries where N is the number of library blocks (typically small)
+            for (BlockPos pos : libraryPositions) {
+                if (!(level.getBlockEntity(pos) instanceof LibraryBlockEntity library)) {
+                    continue;
+                }
 
-                    // Check each disk slot in the library block
-                    LibraryDefinitions defs = library.getDefinitionsForLibrary(libraryName);
-                    if (defs != null) {
-                        return Optional.of(defs);
-                    }
+                LibraryDefinitions defs = library.getDefinitionsForLibrary(libraryName);
+                if (defs != null) {
+                    return Optional.of(defs);
                 }
             }
 
diff --git a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
index c302aeacf..5bb7c66bc 100644
--- a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
+++ b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
@@ -1,6 +1,8 @@
 package ca.teamdman.sfm.common.cablenetwork;
 
+import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
 import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
+import ca.teamdman.sfm.common.label.LabelPositionHolder;
 import ca.teamdman.sfm.common.capability.SFMBlockCapabilityDiscovery;
 import ca.teamdman.sfm.common.capability.SFMBlockCapabilityKind;
 import ca.teamdman.sfm.common.capability.SFMBlockCapabilityResult;
@@ -28,6 +30,12 @@ public class CableNetwork {
     protected final LongSet cablePositions = new LongOpenHashSet();
     protected final SFMBlockCapabilityCacheForLevel levelCapabilityCache;
 
+    /**
+     * Cached label positions for auto-discovered blocks (e.g., library blocks).
+     * This is populated lazily and cleared when the network is rebuilt.
+     */
+    private @Nullable LabelPositionHolder autoLabelCache = null;
+
     public CableNetwork(Level level) {
         this.level = level;
         this.levelCapabilityCache = new SFMBlockCapabilityCacheForLevel(level);
@@ -53,6 +61,7 @@ public static boolean isCable(
     public void rebuildNetwork(BlockPos start) {
         cablePositions.clear();
         levelCapabilityCache.clear();
+        autoLabelCache = null;
         discoverCables(getLevel(), start).forEach(this::addCable);
     }
 
@@ -62,6 +71,7 @@ public void rebuildNetworkFromCache(
     ) {
         cablePositions.clear();
         levelCapabilityCache.clear();
+        autoLabelCache = null;
 
         // discover connected cables
         var cables = SFMStreamUtils.<BlockPos, BlockPos>getRecursiveStream(
@@ -205,6 +215,45 @@ public Stream<BlockPos> getCapabilityProviderPositions() {
         return levelCapabilityCache.getPositions();
     }
 
+    /**
+     * Gets or rebuilds the auto-discovered label cache.
+     * This cache contains positions of special blocks adjacent to cables,
+     * such as library blocks which are auto-labeled with {@link LibraryBlockEntity#LIBRARY_LABEL}.
+     *
+     * @return the auto-discovered label position holder
+     */
+    public LabelPositionHolder getOrRebuildAutoLabels() {
+        if (autoLabelCache != null) {
+            return autoLabelCache;
+        }
+
+        autoLabelCache = LabelPositionHolder.empty();
+
+        // Discover library blocks adjacent to cables
+        LongSet visited = new LongOpenHashSet();
+        BlockPos.MutableBlockPos target = new BlockPos.MutableBlockPos();
+
+        for (long cablePosLong : cablePositions) {
+            BlockPos cablePos = BlockPos.of(cablePosLong);
+            for (Direction direction : SFMDirections.DIRECTIONS_WITHOUT_NULL) {
+                target.set(cablePos).move(direction);
+                long targetLong = target.asLong();
+
+                // Skip if already visited
+                if (!visited.add(targetLong)) {
+                    continue;
+                }
+
+                // Check if this is a library block
+                if (level.getBlockEntity(target) instanceof LibraryBlockEntity) {
+                    autoLabelCache.add(LibraryBlockEntity.LIBRARY_LABEL, target.immutable());
+                }
+            }
+        }
+
+        return autoLabelCache;
+    }
+
     public void bustCacheForChunk(ChunkAccess chunkAccess) {
         levelCapabilityCache.bustCacheForChunk(chunkAccess);
     }

From bbef8e3dffa64f782287192552fd2071acc85161 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 01:59:57 +0100
Subject: [PATCH 16/33] fix: auto-revalidate programs when library blocks
 change

---
 .../sfm/client/screen/LibraryScreen.java      |  5 +-
 .../sfm/common/block/LibraryBlock.java        | 34 ++++++++++++-
 .../blockentity/LibraryBlockEntity.java       | 24 +++++++--
 .../blockentity/ManagerBlockEntity.java       |  6 +++
 .../sfm/common/cablenetwork/CableNetwork.java | 50 +++++++++++++++++--
 5 files changed, 107 insertions(+), 12 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java b/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
index 6bb42b14b..82b542b05 100644
--- a/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
+++ b/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
@@ -80,9 +80,10 @@ private void refreshLibraryEntries() {
 
             String source = DiskItem.getProgramString(disk);
             String name = LibraryBlockEntity.extractName(source);
-            if (name != null && !name.isEmpty()) {
-                entries.add(new LibraryEntry(name, i));
+            if (name == null || name.isEmpty()) {
+                name = "(unnamed)";
             }
+            entries.add(new LibraryEntry(name, i));
         }
         menu.libraryEntries = entries;
     }
diff --git a/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java b/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java
index 54027292b..6f1183fdf 100644
--- a/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java
+++ b/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java
@@ -1,6 +1,8 @@
 package ca.teamdman.sfm.common.block;
 
 import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
+import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
+import ca.teamdman.sfm.common.cablenetwork.CableNetwork;
 import ca.teamdman.sfm.common.cablenetwork.CableNetworkManager;
 import ca.teamdman.sfm.common.cablenetwork.ICableBlock;
 import ca.teamdman.sfm.common.containermenu.LibraryContainerMenu;
@@ -29,6 +31,9 @@
 import net.minecraftforge.network.NetworkHooks;
 import org.jetbrains.annotations.Nullable;
 
+import java.util.HashSet;
+import java.util.Set;
+
 /**
  * A block that stores SFML library definitions (protocols, structs, macros).
  * Can be referenced by manager programs via "use library" statements.
@@ -94,12 +99,18 @@ public InteractionResult use(
     @SuppressWarnings("deprecation")
     public void onPlace(
             BlockState state,
-            Level world,
+            Level level,
             BlockPos pos,
             BlockState oldState,
             boolean isMoving
     ) {
-        CableNetworkManager.onCablePlaced(world, pos);
+        CableNetworkManager.onCablePlaced(level, pos);
+        // Notify managers that a library block was added
+        if (!level.isClientSide()) {
+            CableNetworkManager.getNetworksForLevel(level)
+                    .filter(network -> network.isAdjacentToCable(pos))
+                    .forEach(CableNetwork::invalidateAutoLabelsAndNotifyManagers);
+        }
     }
 
     @Override
@@ -112,12 +123,31 @@ public void onRemove(
             boolean isMoving
     ) {
         if (!state.is(newState.getBlock())) {
+            // Capture managers to notify BEFORE removal (while library still exists in cache)
+            Set<BlockPos> managersToNotify = new HashSet<>();
+            if (!level.isClientSide()) {
+                CableNetworkManager.getNetworksForLevel(level)
+                        .filter(network -> network.isAdjacentToCable(pos))
+                        .forEach(network -> {
+                            managersToNotify.addAll(network.getOrRebuildAutoLabels()
+                                    .getPositions(ManagerBlockEntity.MANAGER_LABEL));
+                            network.invalidateAutoLabelCache();
+                        });
+            }
+
             // Drop all disks when block is broken
             if (level.getBlockEntity(pos) instanceof LibraryBlockEntity library) {
                 Containers.dropContents(level, pos, library);
             }
             CableNetworkManager.onCableRemoved(level, pos);
             super.onRemove(state, level, pos, newState, isMoving);
+
+            // NOW notify managers (after library is fully removed)
+            for (BlockPos managerPos : managersToNotify) {
+                if (level.getBlockEntity(managerPos) instanceof ManagerBlockEntity manager) {
+                    manager.rebuildProgramAndUpdateDisk();
+                }
+            }
         }
     }
 }
diff --git a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
index 64f72e67e..1af0c4e9b 100644
--- a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
+++ b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
@@ -2,6 +2,8 @@
 
 import ca.teamdman.langs.SFMLLexer;
 import ca.teamdman.langs.SFMLParser;
+import ca.teamdman.sfm.common.cablenetwork.CableNetwork;
+import ca.teamdman.sfm.common.cablenetwork.CableNetworkManager;
 import ca.teamdman.sfm.common.containermenu.LibraryContainerMenu;
 import ca.teamdman.sfm.common.item.DiskItem;
 import ca.teamdman.sfm.common.localization.LocalizationKeys;
@@ -83,7 +85,7 @@ public LibraryBlockEntity(BlockPos pos, BlockState state) {
 
     /**
      * Gets library entries with their slot indices from inserted disks.
-     * Only returns entries from disks that have a valid NAME statement.
+     * Disks without a NAME statement are shown with a placeholder name.
      */
     public List<LibraryContainerMenu.LibraryEntry> getLibraryEntries() {
         List<LibraryContainerMenu.LibraryEntry> entries = new ArrayList<>();
@@ -93,9 +95,10 @@ public List<LibraryContainerMenu.LibraryEntry> getLibraryEntries() {
 
             String source = DiskItem.getProgramString(disk);
             String name = extractName(source);
-            if (name != null && !name.isEmpty()) {
-                entries.add(new LibraryContainerMenu.LibraryEntry(name, i));
+            if (name == null || name.isEmpty()) {
+                name = "(unnamed)";
             }
+            entries.add(new LibraryContainerMenu.LibraryEntry(name, i));
         }
         return entries;
     }
@@ -269,9 +272,24 @@ public void setChanged() {
         // Sync to client for renderer updates
         if (level != null && !level.isClientSide()) {
             level.sendBlockUpdated(worldPosition, getBlockState(), getBlockState(), 3);
+            // Notify cable networks that library configuration may have changed
+            notifyNetworkLibraryChanged();
         }
     }
 
+    /**
+     * Notifies any cable networks adjacent to this library block that the library
+     * configuration has changed, causing managers to re-validate their programs.
+     */
+    private void notifyNetworkLibraryChanged() {
+        if (level == null || level.isClientSide()) return;
+
+        // Find networks adjacent to this library block and notify them
+        CableNetworkManager.getNetworksForLevel(level)
+                .filter(network -> network.isAdjacentToCable(worldPosition))
+                .forEach(CableNetwork::invalidateAutoLabelsAndNotifyManagers);
+    }
+
     // Client sync methods for BlockEntityRenderer
     @Override
     public CompoundTag getUpdateTag() {
diff --git a/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java b/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java
index 36358f62f..84d9f0a44 100644
--- a/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java
+++ b/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java
@@ -52,6 +52,12 @@
 import java.util.Set;
 
 public class ManagerBlockEntity extends BaseContainerBlockEntity {
+    /**
+     * Reserved label used to identify manager blocks in the cable network.
+     * This label is auto-registered when the network discovers manager blocks.
+     */
+    public static final String MANAGER_LABEL = "sfm:manager";
+
     public static final int TICK_TIME_HISTORY_SIZE = 20;
 
     public final TranslatableLogger logger;
diff --git a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
index 5bb7c66bc..91b1ee50f 100644
--- a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
+++ b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
@@ -21,6 +21,7 @@
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Set;
 import java.util.stream.Stream;
 
 /// When a {@link ManagerBlockEntity} is ticking many times in a row, there is worldly context that changes infrequently.
@@ -217,8 +218,9 @@ public Stream<BlockPos> getCapabilityProviderPositions() {
 
     /**
      * Gets or rebuilds the auto-discovered label cache.
-     * This cache contains positions of special blocks adjacent to cables,
-     * such as library blocks which are auto-labeled with {@link LibraryBlockEntity#LIBRARY_LABEL}.
+     * This cache contains positions of special blocks on the network:
+     * - Manager blocks (cables): labeled with {@link ManagerBlockEntity#MANAGER_LABEL}
+     * - Library blocks (adjacent to cables): labeled with {@link LibraryBlockEntity#LIBRARY_LABEL}
      *
      * @return the auto-discovered label position holder
      */
@@ -229,18 +231,25 @@ public LabelPositionHolder getOrRebuildAutoLabels() {
 
         autoLabelCache = LabelPositionHolder.empty();
 
-        // Discover library blocks adjacent to cables
-        LongSet visited = new LongOpenHashSet();
+        // Discover managers (which are cables) and library blocks (adjacent to cables)
+        LongSet visitedAdjacent = new LongOpenHashSet();
         BlockPos.MutableBlockPos target = new BlockPos.MutableBlockPos();
 
         for (long cablePosLong : cablePositions) {
             BlockPos cablePos = BlockPos.of(cablePosLong);
+
+            // Check if the cable itself is a manager
+            if (level.getBlockEntity(cablePos) instanceof ManagerBlockEntity) {
+                autoLabelCache.add(ManagerBlockEntity.MANAGER_LABEL, cablePos);
+            }
+
+            // Check adjacent positions for library blocks
             for (Direction direction : SFMDirections.DIRECTIONS_WITHOUT_NULL) {
                 target.set(cablePos).move(direction);
                 long targetLong = target.asLong();
 
                 // Skip if already visited
-                if (!visited.add(targetLong)) {
+                if (!visitedAdjacent.add(targetLong)) {
                     continue;
                 }
 
@@ -256,6 +265,37 @@ public LabelPositionHolder getOrRebuildAutoLabels() {
 
     public void bustCacheForChunk(ChunkAccess chunkAccess) {
         levelCapabilityCache.bustCacheForChunk(chunkAccess);
+        autoLabelCache = null;
+    }
+
+    /**
+     * Invalidates the auto-label cache without notifying managers.
+     * Use this when you need to capture manager positions before a change,
+     * then notify them manually after the change is complete.
+     */
+    public void invalidateAutoLabelCache() {
+        autoLabelCache = null;
+    }
+
+    /**
+     * Invalidates the auto-label cache and notifies all managers on this network
+     * to re-validate their programs. Call this when library blocks are added/removed
+     * or when their contents change.
+     */
+    public void invalidateAutoLabelsAndNotifyManagers() {
+        // Get manager positions BEFORE invalidating the cache
+        Set<BlockPos> managerPositions = getOrRebuildAutoLabels()
+                .getPositions(ManagerBlockEntity.MANAGER_LABEL);
+
+        // Now invalidate the cache
+        autoLabelCache = null;
+
+        // Notify all managers to re-validate their programs
+        for (BlockPos pos : managerPositions) {
+            if (level.getBlockEntity(pos) instanceof ManagerBlockEntity manager) {
+                manager.rebuildProgramAndUpdateDisk();
+            }
+        }
     }
 
     /**

From 804a13812fb38b0dd0d2bad93c4a281bdce3d6a4 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 02:15:16 +0100
Subject: [PATCH 17/33] refactor: consolidate code duplication and improve
 maintainability

---
 .../sfm/client/screen/LibraryScreen.java      |  20 +--
 .../blockentity/LibraryBlockEntity.java       |  45 +----
 .../containermenu/LibraryContainerMenu.java   |  45 ++++-
 .../ca/teamdman/sfm/common/item/DiskItem.java |  35 ++++
 ...erverboundLibraryDiskSetProgramPacket.java |   2 +-
 .../program/linting/MacroUsageLinter.java     |  79 --------
 .../program/linting/ProtocolUsageLinter.java  |  75 --------
 .../program/linting/StructUsageLinter.java    |  92 ----------
 .../linting/UnusedDefinitionLinter.java       | 168 ++++++++++++++++++
 .../common/registry/SFMProgramLinters.java    |  20 +--
 .../java/ca/teamdman/sfml/ast/ASTBuilder.java |  81 ++++-----
 11 files changed, 297 insertions(+), 365 deletions(-)
 delete mode 100644 src/main/java/ca/teamdman/sfm/common/program/linting/MacroUsageLinter.java
 delete mode 100644 src/main/java/ca/teamdman/sfm/common/program/linting/ProtocolUsageLinter.java
 delete mode 100644 src/main/java/ca/teamdman/sfm/common/program/linting/StructUsageLinter.java
 create mode 100644 src/main/java/ca/teamdman/sfm/common/program/linting/UnusedDefinitionLinter.java

diff --git a/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java b/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
index 82b542b05..346ad7351 100644
--- a/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
+++ b/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
@@ -17,9 +17,6 @@
 import net.minecraft.world.entity.player.Inventory;
 import net.minecraft.world.item.ItemStack;
 
-import java.util.ArrayList;
-import java.util.List;
-
 /**
  * Client-side screen for the library block.
  * Shows disk slots and displays available library names from inserted disks
@@ -73,24 +70,13 @@ protected void containerTick() {
     }
 
     private void refreshLibraryEntries() {
-        List<LibraryEntry> entries = new ArrayList<>();
-        for (int i = 0; i < LibraryBlockEntity.DISK_SLOT_COUNT; i++) {
-            ItemStack disk = menu.CONTAINER.getItem(i);
-            if (disk.isEmpty() || !(disk.getItem() instanceof DiskItem)) continue;
-
-            String source = DiskItem.getProgramString(disk);
-            String name = LibraryBlockEntity.extractName(source);
-            if (name == null || name.isEmpty()) {
-                name = "(unnamed)";
-            }
-            entries.add(new LibraryEntry(name, i));
-        }
-        menu.libraryEntries = entries;
+        menu.libraryEntries = LibraryContainerMenu.extractLibraryEntries(
+                menu.CONTAINER, LibraryBlockEntity.DISK_SLOT_COUNT);
     }
 
     private void openEditorForSlot(int slotIndex) {
         ItemStack disk = menu.CONTAINER.getItem(slotIndex);
-        if (disk.isEmpty() || !(disk.getItem() instanceof DiskItem)) return;
+        if (!DiskItem.isValidDisk(disk)) return;
 
         String source = DiskItem.getProgramString(disk);
         SFMScreenChangeHelpers.showProgramEditScreen(new SFMTextEditScreenLibraryDiskOpenContext(
diff --git a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
index 1af0c4e9b..c73a93ad3 100644
--- a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
+++ b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
@@ -36,8 +36,6 @@
 
 import java.util.ArrayList;
 import java.util.List;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
 
 /**
  * Block entity for library blocks that store disks containing SFML definitions.
@@ -54,53 +52,18 @@ public class LibraryBlockEntity extends BaseContainerBlockEntity {
 
     public static final int DISK_SLOT_COUNT = 10;
 
-    /**
-     * Pattern to extract NAME from source code.
-     * Matches: NAME "some_name" (case-insensitive)
-     * Supports escaped quotes in the name.
-     */
-    private static final Pattern NAME_PATTERN = Pattern.compile(
-            "(?i)\\bNAME\\s+\"([^\"\\\\]*(\\\\.[^\"\\\\]*)*)\"");
-
     private final NonNullList<ItemStack> ITEMS = NonNullList.withSize(DISK_SLOT_COUNT, ItemStack.EMPTY);
 
     public LibraryBlockEntity(BlockPos pos, BlockState state) {
         super(SFMBlockEntities.LIBRARY_BLOCK_ENTITY.get(), pos, state);
     }
 
-    /**
-     * Extracts the NAME from SFML source code using regex (fast, avoids full ANTLR parsing).
-     *
-     * @param source The SFML source code
-     * @return The extracted name, or null if not found
-     */
-    public static @Nullable String extractName(String source) {
-        if (source == null || source.isEmpty()) return null;
-        Matcher matcher = NAME_PATTERN.matcher(source);
-        if (matcher.find()) {
-            return matcher.group(1).replace("\\\"", "\"");
-        }
-        return null;
-    }
-
     /**
      * Gets library entries with their slot indices from inserted disks.
      * Disks without a NAME statement are shown with a placeholder name.
      */
     public List<LibraryContainerMenu.LibraryEntry> getLibraryEntries() {
-        List<LibraryContainerMenu.LibraryEntry> entries = new ArrayList<>();
-        for (int i = 0; i < DISK_SLOT_COUNT; i++) {
-            ItemStack disk = getItem(i);
-            if (disk.isEmpty() || !(disk.getItem() instanceof DiskItem)) continue;
-
-            String source = DiskItem.getProgramString(disk);
-            String name = extractName(source);
-            if (name == null || name.isEmpty()) {
-                name = "(unnamed)";
-            }
-            entries.add(new LibraryContainerMenu.LibraryEntry(name, i));
-        }
-        return entries;
+        return LibraryContainerMenu.extractLibraryEntries(this, DISK_SLOT_COUNT);
     }
 
     /**
@@ -112,10 +75,10 @@ public List<LibraryContainerMenu.LibraryEntry> getLibraryEntries() {
     public @Nullable LibraryDefinitions getDefinitionsForLibrary(String libraryName) {
         for (int i = 0; i < DISK_SLOT_COUNT; i++) {
             ItemStack disk = getItem(i);
-            if (disk.isEmpty() || !(disk.getItem() instanceof DiskItem)) continue;
+            if (!DiskItem.isValidDisk(disk)) continue;
 
             String source = DiskItem.getProgramString(disk);
-            String name = extractName(source);
+            String name = DiskItem.extractName(source);
 
             if (libraryName.equals(name)) {
                 return parseLibraryDefinitions(source);
@@ -323,7 +286,7 @@ public void onDataPacket(net.minecraft.network.Connection net, ClientboundBlockE
     private int computeDiskMask() {
         int mask = 0;
         for (int i = 0; i < ITEMS.size(); i++) {
-            if (!ITEMS.get(i).isEmpty() && ITEMS.get(i).getItem() instanceof DiskItem) {
+            if (DiskItem.isValidDisk(ITEMS.get(i))) {
                 mask |= (1 << i);
             }
         }
diff --git a/src/main/java/ca/teamdman/sfm/common/containermenu/LibraryContainerMenu.java b/src/main/java/ca/teamdman/sfm/common/containermenu/LibraryContainerMenu.java
index ec072ee68..3c10c08f8 100644
--- a/src/main/java/ca/teamdman/sfm/common/containermenu/LibraryContainerMenu.java
+++ b/src/main/java/ca/teamdman/sfm/common/containermenu/LibraryContainerMenu.java
@@ -21,11 +21,46 @@
  */
 public class LibraryContainerMenu extends AbstractContainerMenu {
 
+    // Disk slot layout constants
+    private static final int DISK_SLOT_START_X = 44;
+    private static final int DISK_SLOT_START_Y = 20;
+    private static final int SLOT_SPACING = 18;
+    private static final int DISK_SLOTS_PER_ROW = 5;
+
+    // Player inventory layout constants
+    private static final int PLAYER_INV_START_X = 8;
+    private static final int PLAYER_INV_START_Y = 84;
+    private static final int PLAYER_HOTBAR_Y = 142;
+
     /**
      * Record to track library name and its slot index.
      */
     public record LibraryEntry(String name, int slotIndex) {}
 
+    /**
+     * Extracts library entries from a container's disk slots.
+     * Used by both server-side (LibraryBlockEntity) and client-side (refreshing from synced container).
+     *
+     * @param container The container to extract entries from
+     * @param slotCount The number of disk slots to check
+     * @return List of library entries with their names and slot indices
+     */
+    public static List<LibraryEntry> extractLibraryEntries(Container container, int slotCount) {
+        List<LibraryEntry> entries = new ArrayList<>();
+        for (int i = 0; i < slotCount; i++) {
+            ItemStack disk = container.getItem(i);
+            if (!DiskItem.isValidDisk(disk)) continue;
+
+            String source = DiskItem.getProgramString(disk);
+            String name = DiskItem.extractName(source);
+            if (name == null || name.isEmpty()) {
+                name = "(unnamed)";
+            }
+            entries.add(new LibraryEntry(name, i));
+        }
+        return entries;
+    }
+
     public final Inventory PLAYER_INVENTORY;
     public final BlockPos LIBRARY_POSITION;
     public final Container CONTAINER;
@@ -46,8 +81,8 @@ public LibraryContainerMenu(
 
         // Add disk slots (2 rows of 5)
         for (int i = 0; i < LibraryBlockEntity.DISK_SLOT_COUNT; i++) {
-            int x = 44 + (i % 5) * 18;
-            int y = 20 + (i / 5) * 18;
+            int x = DISK_SLOT_START_X + (i % DISK_SLOTS_PER_ROW) * SLOT_SPACING;
+            int y = DISK_SLOT_START_Y + (i / DISK_SLOTS_PER_ROW) * SLOT_SPACING;
             this.addSlot(new Slot(container, i, x, y) {
                 @Override
                 public boolean mayPlace(ItemStack stack) {
@@ -59,13 +94,15 @@ public boolean mayPlace(ItemStack stack) {
         // Add player inventory slots
         for (int i = 0; i < 3; ++i) {
             for (int j = 0; j < 9; ++j) {
-                this.addSlot(new Slot(inv, j + i * 9 + 9, 8 + j * 18, 84 + i * 18));
+                this.addSlot(new Slot(inv, j + i * 9 + 9,
+                        PLAYER_INV_START_X + j * SLOT_SPACING,
+                        PLAYER_INV_START_Y + i * SLOT_SPACING));
             }
         }
 
         // Add player hotbar slots
         for (int k = 0; k < 9; ++k) {
-            this.addSlot(new Slot(inv, k, 8 + k * 18, 142));
+            this.addSlot(new Slot(inv, k, PLAYER_INV_START_X + k * SLOT_SPACING, PLAYER_HOTBAR_Y));
         }
     }
 
diff --git a/src/main/java/ca/teamdman/sfm/common/item/DiskItem.java b/src/main/java/ca/teamdman/sfm/common/item/DiskItem.java
index 1fe480dd9..6656824a8 100644
--- a/src/main/java/ca/teamdman/sfm/common/item/DiskItem.java
+++ b/src/main/java/ca/teamdman/sfm/common/item/DiskItem.java
@@ -38,13 +38,48 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 
 public class DiskItem extends Item {
+    /**
+     * Pattern to extract NAME from source code.
+     * Matches: NAME "some_name" (case-insensitive)
+     * Supports escaped quotes in the name.
+     */
+    private static final Pattern NAME_PATTERN = Pattern.compile(
+            "(?i)\\bNAME\\s+\"([^\"\\\\]*(\\\\.[^\"\\\\]*)*)\"");
+
     public DiskItem() {
         super(new Item.Properties().tab(SFMCreativeTabs.TAB));
     }
 
+    /**
+     * Checks if an ItemStack is a valid disk item.
+     *
+     * @param stack The ItemStack to check
+     * @return true if the stack is non-empty and contains a DiskItem
+     */
+    public static boolean isValidDisk(ItemStack stack) {
+        return !stack.isEmpty() && stack.getItem() instanceof DiskItem;
+    }
+
+    /**
+     * Extracts the NAME from SFML source code using regex (fast, avoids full ANTLR parsing).
+     *
+     * @param source The SFML source code
+     * @return The extracted name, or null if not found
+     */
+    public static @Nullable String extractName(String source) {
+        if (source == null || source.isEmpty()) return null;
+        Matcher matcher = NAME_PATTERN.matcher(source);
+        if (matcher.find()) {
+            return matcher.group(1).replace("\\\"", "\"");
+        }
+        return null;
+    }
+
     public static String getProgramString(ItemStack stack) {
         return stack
                 .getOrCreateTag()
diff --git a/src/main/java/ca/teamdman/sfm/common/net/ServerboundLibraryDiskSetProgramPacket.java b/src/main/java/ca/teamdman/sfm/common/net/ServerboundLibraryDiskSetProgramPacket.java
index b5ac6a52d..332808481 100644
--- a/src/main/java/ca/teamdman/sfm/common/net/ServerboundLibraryDiskSetProgramPacket.java
+++ b/src/main/java/ca/teamdman/sfm/common/net/ServerboundLibraryDiskSetProgramPacket.java
@@ -75,7 +75,7 @@ public void handle(
 
             // Get the disk in the slot
             ItemStack disk = library.getItem(msg.slotIndex);
-            if (disk.isEmpty() || !(disk.getItem() instanceof DiskItem)) {
+            if (!DiskItem.isValidDisk(disk)) {
                 return;
             }
 
diff --git a/src/main/java/ca/teamdman/sfm/common/program/linting/MacroUsageLinter.java b/src/main/java/ca/teamdman/sfm/common/program/linting/MacroUsageLinter.java
deleted file mode 100644
index 3a0b291e3..000000000
--- a/src/main/java/ca/teamdman/sfm/common/program/linting/MacroUsageLinter.java
+++ /dev/null
@@ -1,79 +0,0 @@
-package ca.teamdman.sfm.common.program.linting;
-
-import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
-import ca.teamdman.sfm.common.label.LabelPositionHolder;
-import ca.teamdman.sfml.ast.ExpandStatement;
-import ca.teamdman.sfml.ast.MacroDefinition;
-import ca.teamdman.sfml.ast.Program;
-import ca.teamdman.sfml.ast.Statement;
-import ca.teamdman.sfml.ast.Trigger;
-import net.minecraft.world.item.ItemStack;
-import net.minecraft.world.level.Level;
-import org.jetbrains.annotations.Nullable;
-
-import java.util.ArrayDeque;
-import java.util.Deque;
-import java.util.HashSet;
-import java.util.Set;
-
-import static ca.teamdman.sfm.common.localization.LocalizationKeys.PROGRAM_WARNING_UNUSED_MACRO;
-
-/**
- * Linter that validates macro usage.
- * Warns if a macro is defined but never expanded.
- */
-public class MacroUsageLinter implements IProgramLinter {
-    @Override
-    public void gatherWarnings(
-            Program program,
-            LabelPositionHolder labelPositionHolder,
-            @Nullable ManagerBlockEntity managerBlockEntity,
-            ProblemTracker tracker
-    ) {
-        // Skip for library disks (no triggers = definitions are meant to be exported)
-        if (program.triggers().isEmpty()) {
-            return;
-        }
-
-        // Collect all macro names that are used in expand statements
-        Set<String> usedMacros = new HashSet<>();
-        collectUsedMacros(program, usedMacros);
-
-        // Check for unused macro definitions
-        for (MacroDefinition macroDef : program.macroDefinitions()) {
-            if (!usedMacros.contains(macroDef.name())) {
-                if (tracker.add(PROGRAM_WARNING_UNUSED_MACRO.get(macroDef.name())).isSaturated()) {
-                    return;
-                }
-            }
-        }
-    }
-
-    private void collectUsedMacros(Program program, Set<String> usedMacros) {
-        Deque<Statement> toVisit = new ArrayDeque<>();
-        for (Trigger trigger : program.triggers()) {
-            toVisit.addAll(trigger.getStatements());
-        }
-
-        while (!toVisit.isEmpty()) {
-            Statement stmt = toVisit.poll();
-
-            if (stmt instanceof ExpandStatement expand) {
-                usedMacros.add(expand.macroName());
-            }
-
-            toVisit.addAll(stmt.getStatements());
-        }
-    }
-
-    @Override
-    public void fixWarnings(
-            Program program,
-            LabelPositionHolder labels,
-            ManagerBlockEntity manager,
-            Level level,
-            ItemStack disk
-    ) {
-        // Cannot auto-fix - removing unused macros would require modifying source code
-    }
-}
diff --git a/src/main/java/ca/teamdman/sfm/common/program/linting/ProtocolUsageLinter.java b/src/main/java/ca/teamdman/sfm/common/program/linting/ProtocolUsageLinter.java
deleted file mode 100644
index 8f9c35125..000000000
--- a/src/main/java/ca/teamdman/sfm/common/program/linting/ProtocolUsageLinter.java
+++ /dev/null
@@ -1,75 +0,0 @@
-package ca.teamdman.sfm.common.program.linting;
-
-import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
-import ca.teamdman.sfm.common.label.LabelPositionHolder;
-import ca.teamdman.sfml.ast.MacroDefinition;
-import ca.teamdman.sfml.ast.MacroParameter;
-import ca.teamdman.sfml.ast.Program;
-import ca.teamdman.sfml.ast.ProtocolDefinition;
-import ca.teamdman.sfml.ast.StructDefinition;
-import net.minecraft.world.item.ItemStack;
-import net.minecraft.world.level.Level;
-import org.jetbrains.annotations.Nullable;
-
-import java.util.HashSet;
-import java.util.Set;
-
-import static ca.teamdman.sfm.common.localization.LocalizationKeys.PROGRAM_WARNING_UNUSED_PROTOCOL;
-
-/**
- * Linter that warns about protocols that are defined but never used.
- * A protocol is "used" if:
- * - A struct implements it
- * - A macro parameter is constrained by it
- */
-public class ProtocolUsageLinter implements IProgramLinter {
-    @Override
-    public void gatherWarnings(
-            Program program,
-            LabelPositionHolder labelPositionHolder,
-            @Nullable ManagerBlockEntity managerBlockEntity,
-            ProblemTracker tracker
-    ) {
-        // Skip for library disks (no triggers = definitions are meant to be exported)
-        if (program.triggers().isEmpty()) {
-            return;
-        }
-
-        // Collect all protocols that are referenced
-        Set<String> usedProtocols = new HashSet<>();
-
-        // Protocols implemented by structs
-        for (StructDefinition structDef : program.structDefinitions()) {
-            usedProtocols.addAll(structDef.implementedProtocols());
-        }
-
-        // Protocols used as macro parameter constraints
-        for (MacroDefinition macroDef : program.macroDefinitions()) {
-            for (MacroParameter param : macroDef.parameters()) {
-                if (param.protocolConstraint() != null) {
-                    usedProtocols.add(param.protocolConstraint());
-                }
-            }
-        }
-
-        // Check for unused protocol definitions
-        for (ProtocolDefinition protocolDef : program.protocolDefinitions()) {
-            if (!usedProtocols.contains(protocolDef.name())) {
-                if (tracker.add(PROGRAM_WARNING_UNUSED_PROTOCOL.get(protocolDef.name())).isSaturated()) {
-                    return;
-                }
-            }
-        }
-    }
-
-    @Override
-    public void fixWarnings(
-            Program program,
-            LabelPositionHolder labels,
-            ManagerBlockEntity manager,
-            Level level,
-            ItemStack disk
-    ) {
-        // Cannot auto-fix - removing unused protocols would require modifying source code
-    }
-}
diff --git a/src/main/java/ca/teamdman/sfm/common/program/linting/StructUsageLinter.java b/src/main/java/ca/teamdman/sfm/common/program/linting/StructUsageLinter.java
deleted file mode 100644
index e6ff299ae..000000000
--- a/src/main/java/ca/teamdman/sfm/common/program/linting/StructUsageLinter.java
+++ /dev/null
@@ -1,92 +0,0 @@
-package ca.teamdman.sfm.common.program.linting;
-
-import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
-import ca.teamdman.sfm.common.label.LabelPositionHolder;
-import ca.teamdman.sfml.ast.*;
-import net.minecraft.world.item.ItemStack;
-import net.minecraft.world.level.Level;
-import org.jetbrains.annotations.Nullable;
-
-import java.util.HashSet;
-import java.util.Set;
-
-import static ca.teamdman.sfm.common.localization.LocalizationKeys.PROGRAM_WARNING_UNUSED_STRUCT_INSTANCE;
-
-/**
- * Linter that validates struct instances are actually used.
- */
-public class StructUsageLinter implements IProgramLinter {
-    @Override
-    public void gatherWarnings(
-            Program program,
-            LabelPositionHolder labelPositionHolder,
-            @Nullable ManagerBlockEntity managerBlockEntity,
-            ProblemTracker tracker
-    ) {
-        // Collect all struct instance variable names that are used in USING clauses
-        Set<String> usedInstances = new HashSet<>();
-        collectUsedInstances(program, usedInstances);
-
-        // Check for unused struct instances
-        for (LetStatement letStatement : program.letStatements()) {
-            String variableName = letStatement.variableName();
-            if (!usedInstances.contains(variableName)) {
-                if (tracker.add(PROGRAM_WARNING_UNUSED_STRUCT_INSTANCE.get(variableName)).isSaturated()) {
-                    return;
-                }
-            }
-        }
-    }
-
-    private void collectUsedInstances(ASTNode node, Set<String> usedInstances) {
-        if (node instanceof LabelAccess labelAccess) {
-            StructAccess structAccess = labelAccess.structAccess();
-            if (structAccess != null) {
-                usedInstances.add(structAccess.variableName());
-            }
-        }
-
-        // Recursively check child statements
-        for (Statement child : node.getStatements()) {
-            collectUsedInstances(child, usedInstances);
-
-            // Check label access in IO statements
-            if (child instanceof IOStatement ioStatement) {
-                LabelAccess labelAccess = ioStatement.labelAccess();
-                if (labelAccess.structAccess() != null) {
-                    usedInstances.add(labelAccess.structAccess().variableName());
-                }
-            }
-
-            // Check label access in BoolHas expressions
-            if (child instanceof IfStatement ifStatement) {
-                collectUsedInstancesFromBoolExpr(ifStatement, usedInstances);
-            }
-        }
-    }
-
-    private void collectUsedInstancesFromBoolExpr(IfStatement ifStatement, Set<String> usedInstances) {
-        // This is a simplified approach - a full implementation would need to walk
-        // the entire AST tree including all BoolExpr nodes
-        ifStatement.getDescendantStatements().forEach(stmt -> {
-            if (stmt instanceof IOStatement ioStatement) {
-                LabelAccess labelAccess = ioStatement.labelAccess();
-                if (labelAccess.structAccess() != null) {
-                    usedInstances.add(labelAccess.structAccess().variableName());
-                }
-            }
-        });
-    }
-
-    @Override
-    public void fixWarnings(
-            Program program,
-            LabelPositionHolder labels,
-            ManagerBlockEntity manager,
-            Level level,
-            ItemStack disk
-    ) {
-        // We can't auto-fix this - removing unused struct instances would require
-        // modifying the program source code
-    }
-}
diff --git a/src/main/java/ca/teamdman/sfm/common/program/linting/UnusedDefinitionLinter.java b/src/main/java/ca/teamdman/sfm/common/program/linting/UnusedDefinitionLinter.java
new file mode 100644
index 000000000..f3a1b33ae
--- /dev/null
+++ b/src/main/java/ca/teamdman/sfm/common/program/linting/UnusedDefinitionLinter.java
@@ -0,0 +1,168 @@
+package ca.teamdman.sfm.common.program.linting;
+
+import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
+import ca.teamdman.sfm.common.label.LabelPositionHolder;
+import ca.teamdman.sfml.ast.*;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.Level;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.ArrayDeque;
+import java.util.Deque;
+import java.util.HashSet;
+import java.util.Set;
+
+import static ca.teamdman.sfm.common.localization.LocalizationKeys.*;
+
+/**
+ * Linter that validates definitions (protocols, macros, struct instances) are actually used.
+ * Consolidates checks for:
+ * - Unused protocol definitions
+ * - Unused macro definitions
+ * - Unused struct instances (let statements)
+ */
+public class UnusedDefinitionLinter implements IProgramLinter {
+    @Override
+    public void gatherWarnings(
+            Program program,
+            LabelPositionHolder labelPositionHolder,
+            @Nullable ManagerBlockEntity managerBlockEntity,
+            ProblemTracker tracker
+    ) {
+        // Skip for library disks (no triggers = definitions are meant to be exported)
+        if (program.triggers().isEmpty()) {
+            return;
+        }
+
+        checkUnusedProtocols(program, tracker);
+        if (tracker.isSaturated()) return;
+
+        checkUnusedMacros(program, tracker);
+        if (tracker.isSaturated()) return;
+
+        checkUnusedStructInstances(program, tracker);
+    }
+
+    private void checkUnusedProtocols(Program program, ProblemTracker tracker) {
+        // Collect all protocols that are referenced
+        Set<String> usedProtocols = new HashSet<>();
+
+        // Protocols implemented by structs
+        for (StructDefinition structDef : program.structDefinitions()) {
+            usedProtocols.addAll(structDef.implementedProtocols());
+        }
+
+        // Protocols used as macro parameter constraints
+        for (MacroDefinition macroDef : program.macroDefinitions()) {
+            for (MacroParameter param : macroDef.parameters()) {
+                if (param.protocolConstraint() != null) {
+                    usedProtocols.add(param.protocolConstraint());
+                }
+            }
+        }
+
+        // Check for unused protocol definitions
+        for (ProtocolDefinition protocolDef : program.protocolDefinitions()) {
+            if (!usedProtocols.contains(protocolDef.name())) {
+                if (tracker.add(PROGRAM_WARNING_UNUSED_PROTOCOL.get(protocolDef.name())).isSaturated()) {
+                    return;
+                }
+            }
+        }
+    }
+
+    private void checkUnusedMacros(Program program, ProblemTracker tracker) {
+        // Collect all macro names that are used in expand statements
+        Set<String> usedMacros = new HashSet<>();
+
+        Deque<Statement> toVisit = new ArrayDeque<>();
+        for (Trigger trigger : program.triggers()) {
+            toVisit.addAll(trigger.getStatements());
+        }
+
+        while (!toVisit.isEmpty()) {
+            Statement stmt = toVisit.poll();
+
+            if (stmt instanceof ExpandStatement expand) {
+                usedMacros.add(expand.macroName());
+            }
+
+            toVisit.addAll(stmt.getStatements());
+        }
+
+        // Check for unused macro definitions
+        for (MacroDefinition macroDef : program.macroDefinitions()) {
+            if (!usedMacros.contains(macroDef.name())) {
+                if (tracker.add(PROGRAM_WARNING_UNUSED_MACRO.get(macroDef.name())).isSaturated()) {
+                    return;
+                }
+            }
+        }
+    }
+
+    private void checkUnusedStructInstances(Program program, ProblemTracker tracker) {
+        // Collect all struct instance variable names that are used
+        Set<String> usedInstances = new HashSet<>();
+        collectUsedInstances(program, usedInstances);
+
+        // Check for unused struct instances
+        for (LetStatement letStatement : program.letStatements()) {
+            String variableName = letStatement.variableName();
+            if (!usedInstances.contains(variableName)) {
+                if (tracker.add(PROGRAM_WARNING_UNUSED_STRUCT_INSTANCE.get(variableName)).isSaturated()) {
+                    return;
+                }
+            }
+        }
+    }
+
+    private void collectUsedInstances(ASTNode node, Set<String> usedInstances) {
+        if (node instanceof LabelAccess labelAccess) {
+            StructAccess structAccess = labelAccess.structAccess();
+            if (structAccess != null) {
+                usedInstances.add(structAccess.variableName());
+            }
+        }
+
+        // Recursively check child statements
+        for (Statement child : node.getStatements()) {
+            collectUsedInstances(child, usedInstances);
+
+            // Check label access in IO statements
+            if (child instanceof IOStatement ioStatement) {
+                LabelAccess labelAccess = ioStatement.labelAccess();
+                if (labelAccess.structAccess() != null) {
+                    usedInstances.add(labelAccess.structAccess().variableName());
+                }
+            }
+
+            // Check label access in BoolHas expressions
+            if (child instanceof IfStatement ifStatement) {
+                collectUsedInstancesFromBoolExpr(ifStatement, usedInstances);
+            }
+        }
+    }
+
+    private void collectUsedInstancesFromBoolExpr(IfStatement ifStatement, Set<String> usedInstances) {
+        // Walk the entire AST tree including all BoolExpr nodes
+        ifStatement.getDescendantStatements().forEach(stmt -> {
+            if (stmt instanceof IOStatement ioStatement) {
+                LabelAccess labelAccess = ioStatement.labelAccess();
+                if (labelAccess.structAccess() != null) {
+                    usedInstances.add(labelAccess.structAccess().variableName());
+                }
+            }
+        });
+    }
+
+    @Override
+    public void fixWarnings(
+            Program program,
+            LabelPositionHolder labels,
+            ManagerBlockEntity manager,
+            Level level,
+            ItemStack disk
+    ) {
+        // Cannot auto-fix - removing unused definitions would require modifying source code
+    }
+}
diff --git a/src/main/java/ca/teamdman/sfm/common/registry/SFMProgramLinters.java b/src/main/java/ca/teamdman/sfm/common/registry/SFMProgramLinters.java
index 6f3ff7105..a32436e6f 100644
--- a/src/main/java/ca/teamdman/sfm/common/registry/SFMProgramLinters.java
+++ b/src/main/java/ca/teamdman/sfm/common/registry/SFMProgramLinters.java
@@ -75,22 +75,10 @@ public class SFMProgramLinters {
             StructDefinitionLinter::new
     );
 
-    public static final SFMRegistryObject<IProgramLinter, StructUsageLinter>
-            STRUCT_USAGE_LINTER = REGISTERER.register(
-            "struct_usage",
-            StructUsageLinter::new
-    );
-
-    public static final SFMRegistryObject<IProgramLinter, ProtocolUsageLinter>
-            PROTOCOL_USAGE_LINTER = REGISTERER.register(
-            "protocol_usage",
-            ProtocolUsageLinter::new
-    );
-
-    public static final SFMRegistryObject<IProgramLinter, MacroUsageLinter>
-            MACRO_USAGE_LINTER = REGISTERER.register(
-            "macro_usage",
-            MacroUsageLinter::new
+    public static final SFMRegistryObject<IProgramLinter, UnusedDefinitionLinter>
+            UNUSED_DEFINITION_LINTER = REGISTERER.register(
+            "unused_definition",
+            UnusedDefinitionLinter::new
     );
 
     static {
diff --git a/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java b/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
index 7350cb5b9..953eedfb0 100644
--- a/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
+++ b/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
@@ -48,6 +48,42 @@ public void setLibraryResolver(LibraryResolver resolver) {
         this.libraryResolver = resolver != null ? resolver : LibraryResolver.NONE;
     }
 
+    /**
+     * Registers a definition in a map, throwing if a duplicate name is detected.
+     *
+     * @param definitions The map to register in
+     * @param name The name to register
+     * @param value The value to associate with the name
+     * @param typeName The type name for error messages (e.g., "protocol", "struct", "macro")
+     * @param <T> The type of definition
+     */
+    private <T> void registerDefinition(Map<String, T> definitions, String name, T value, String typeName) {
+        if (definitions.containsKey(name)) {
+            throw new IllegalArgumentException("Duplicate " + typeName + " definition: " + name);
+        }
+        definitions.put(name, value);
+    }
+
+    /**
+     * Builds a ResourceIdSet from a list of resource ID contexts.
+     *
+     * @param resourceIds The list of resource ID contexts to process
+     * @param trackCtx The parser context to track (may be null)
+     * @return A ResourceIdSet containing the parsed resource identifiers
+     */
+    private ResourceIdSet buildResourceIdSet(List<SFMLParser.ResourceIdContext> resourceIds, @Nullable ParserRuleContext trackCtx) {
+        HashSet<ResourceIdentifier<?, ?, ?>> ids = resourceIds
+                .stream()
+                .map(this::visit)
+                .map(ResourceIdentifier.class::cast)
+                .collect(HashSet::new, HashSet::add, HashSet::addAll);
+        ResourceIdSet resourceIdSet = new ResourceIdSet(ids);
+        if (trackCtx != null) {
+            trackNode(resourceIdSet, trackCtx);
+        }
+        return resourceIdSet;
+    }
+
     /// @return hierarchy of nodes; e.g., Program > Trigger > Block > IOStatement > LabelAccess > Label
     public List<Pair<ASTNode, ParserRuleContext>> getNodesUnderCursor(int cursorPos) {
 
@@ -316,11 +352,6 @@ public LibraryStatement visitLibrary(SFMLParser.LibraryContext ctx) {
     public ProtocolDefinition visitProtocolDefinition(SFMLParser.ProtocolDefinitionContext ctx) {
         String name = ctx.identifier().getText();
 
-        // Check for duplicate protocol names
-        if (PROTOCOL_DEFINITIONS.containsKey(name)) {
-            throw new IllegalArgumentException("Duplicate protocol definition: " + name);
-        }
-
         List<ProtocolField> fields = new ArrayList<>();
         Set<String> fieldNames = new HashSet<>();
 
@@ -338,7 +369,7 @@ public ProtocolDefinition visitProtocolDefinition(SFMLParser.ProtocolDefinitionC
         }
 
         ProtocolDefinition protocolDef = new ProtocolDefinition(name, fields);
-        PROTOCOL_DEFINITIONS.put(name, protocolDef);
+        registerDefinition(PROTOCOL_DEFINITIONS, name, protocolDef, "protocol");
         trackNode(protocolDef, ctx);
         return protocolDef;
     }
@@ -377,11 +408,6 @@ public ProtocolFieldType visitProtocolFieldType(SFMLParser.ProtocolFieldTypeCont
     public StructDefinition visitStructDefinition(SFMLParser.StructDefinitionContext ctx) {
         String name = ctx.identifier(0).getText();
 
-        // Check for duplicate struct names
-        if (STRUCT_DEFINITIONS.containsKey(name)) {
-            throw new IllegalArgumentException("Duplicate struct definition: " + name);
-        }
-
         // Collect implemented protocols
         List<String> implementedProtocols = new ArrayList<>();
         for (int i = 1; i < ctx.identifier().size(); i++) {
@@ -415,7 +441,7 @@ public StructDefinition visitStructDefinition(SFMLParser.StructDefinitionContext
             validateProtocolConformance(structDef, PROTOCOL_DEFINITIONS.get(protocolName));
         }
 
-        STRUCT_DEFINITIONS.put(name, structDef);
+        registerDefinition(STRUCT_DEFINITIONS, name, structDef, "struct");
         trackNode(structDef, ctx);
         return structDef;
     }
@@ -563,11 +589,6 @@ private Map.Entry<String, StructFieldValue> parseStructFieldAssignment(SFMLParse
     public MacroDefinition visitMacroDefinition(SFMLParser.MacroDefinitionContext ctx) {
         String name = ctx.identifier().getText();
 
-        // Check for duplicate macro names
-        if (MACRO_DEFINITIONS.containsKey(name)) {
-            throw new IllegalArgumentException("Duplicate macro definition: " + name);
-        }
-
         // Parse parameters
         List<MacroParameter> parameters = new ArrayList<>();
         if (ctx.macroParamList() != null) {
@@ -581,7 +602,7 @@ public MacroDefinition visitMacroDefinition(SFMLParser.MacroDefinitionContext ct
         List<MacroStatement> body = visitMacroBodyStatements(ctx.macroBody());
 
         MacroDefinition macroDef = new MacroDefinition(name, parameters, body);
-        MACRO_DEFINITIONS.put(name, macroDef);
+        registerDefinition(MACRO_DEFINITIONS, name, macroDef, "macro");
         trackNode(macroDef, ctx);
         return macroDef;
     }
@@ -1342,37 +1363,17 @@ public ResourceIdSet visitResourceExclusion(@Nullable SFMLParser.ResourceExclusi
     }
 
     /// This one uses COMMA instead of OR to separate items
-    @SuppressWarnings("DuplicatedCode")
     @Override
     public ResourceIdSet visitResourceIdList(@Nullable SFMLParser.ResourceIdListContext ctx) {
-
         if (ctx == null) return ResourceIdSet.EMPTY;
-        HashSet<ResourceIdentifier<?, ?, ?>> ids = ctx
-                .resourceId()
-                .stream()
-                .map(this::visit)
-                .map(ResourceIdentifier.class::cast)
-                .collect(HashSet::new, HashSet::add, HashSet::addAll);
-        ResourceIdSet resourceIdSet = new ResourceIdSet(ids);
-        trackNode(resourceIdSet, ctx);
-        return resourceIdSet;
+        return buildResourceIdSet(ctx.resourceId(), ctx);
     }
 
     /// This one uses OR instead of COMMA to separate items
-    @SuppressWarnings("DuplicatedCode")
     @Override
     public ResourceIdSet visitResourceIdDisjunction(@Nullable SFMLParser.ResourceIdDisjunctionContext ctx) {
-
         if (ctx == null) return ResourceIdSet.EMPTY;
-        HashSet<ResourceIdentifier<?, ?, ?>> ids = ctx
-                .resourceId()
-                .stream()
-                .map(this::visit)
-                .map(ResourceIdentifier.class::cast)
-                .collect(HashSet::new, HashSet::add, HashSet::addAll);
-        ResourceIdSet resourceIdSet = new ResourceIdSet(ids);
-        trackNode(resourceIdSet, ctx);
-        return resourceIdSet;
+        return buildResourceIdSet(ctx.resourceId(), ctx);
     }
 
     @Override

From 62f7e42b517e080a2bb395adf35aee44d9dccab5 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 12:23:52 +0100
Subject: [PATCH 18/33] feat: replace EXPAND keyword with DO and @ symbol for
 macro invocation

---
 src/main/antlr/sfml/SFML.g4                   |  6 +-
 .../ProgramSyntaxHighlightingHelper.java      |  2 +-
 .../sfm/template_programs/library_blocks.sfml |  2 +-
 .../protocols_and_macros.sfml                 |  6 +-
 src/test/java/ca/teamdman/sfml/SFMLTests.java | 24 ++---
 .../syntaxes/SFML.g4                          | 96 ++++++++++++++++++-
 6 files changed, 113 insertions(+), 23 deletions(-)

diff --git a/src/main/antlr/sfml/SFML.g4 b/src/main/antlr/sfml/SFML.g4
index 7be16c254..e27f88d05 100644
--- a/src/main/antlr/sfml/SFML.g4
+++ b/src/main/antlr/sfml/SFML.g4
@@ -94,7 +94,7 @@ statement       : inputStatement
                 | expandStatement
                 ;
 
-expandStatement : EXPAND identifier LPAREN expandArgList? RPAREN ;
+expandStatement : (DO | AT) identifier LPAREN expandArgList? RPAREN ;
 expandArgList : expandArg (COMMA expandArg)* ;
 expandArg : identifier | string ;
 
@@ -218,7 +218,7 @@ label           : (identifier)  #RawLabel
 
 emptyslots      : EMPTY (SLOTS | SLOT) IN ;
 
-identifier : (IDENTIFIER | REDSTONE | GLOBAL | SECOND | SECONDS | TOP | BOTTOM | LEFT | RIGHT | FRONT | BACK | INPUT | OUTPUT | LABEL | STRUCT | LET | USING | SLOT | SLOTS | SIDE | BLOCK | PROTOCOL | MACRO | EXPAND | USE | LIBRARY | RESOURCE | SIDEQUALIFIER | SLOTQUALIFIER | NUMBERTYPE) ;
+identifier : (IDENTIFIER | REDSTONE | GLOBAL | SECOND | SECONDS | TOP | BOTTOM | LEFT | RIGHT | FRONT | BACK | INPUT | OUTPUT | LABEL | STRUCT | LET | USING | SLOT | SLOTS | SIDE | BLOCK | PROTOCOL | MACRO | DO | USE | LIBRARY | RESOURCE | SIDEQUALIFIER | SLOTQUALIFIER | NUMBERTYPE) ;
 
 // GENERAL
 string: STRING ;
@@ -336,7 +336,7 @@ NUMBERTYPE      : N U M B E R ;
 
 // MACRO SYMBOLS
 MACRO           : M A C R O ;
-EXPAND          : E X P A N D ;
+AT              : '@' ;
 
 // LIBRARY SYMBOLS
 USE             : U S E ;
diff --git a/src/main/java/ca/teamdman/sfm/client/text_styling/ProgramSyntaxHighlightingHelper.java b/src/main/java/ca/teamdman/sfm/client/text_styling/ProgramSyntaxHighlightingHelper.java
index 8623e6e34..a1dd1daf4 100644
--- a/src/main/java/ca/teamdman/sfm/client/text_styling/ProgramSyntaxHighlightingHelper.java
+++ b/src/main/java/ca/teamdman/sfm/client/text_styling/ProgramSyntaxHighlightingHelper.java
@@ -162,7 +162,7 @@ private static ChatFormatting getColour(Token token) {
             case SFMLLexer.LET:
             case SFMLLexer.USING:
             case SFMLLexer.MACRO:
-            case SFMLLexer.EXPAND:
+            case SFMLLexer.AT:
             case SFMLLexer.USE:
             case SFMLLexer.LIBRARY:
                 return ChatFormatting.BLUE;
diff --git a/src/main/resources/assets/sfm/template_programs/library_blocks.sfml b/src/main/resources/assets/sfm/template_programs/library_blocks.sfml
index 558562755..ee236dcd8 100644
--- a/src/main/resources/assets/sfm/template_programs/library_blocks.sfml
+++ b/src/main/resources/assets/sfm/template_programs/library_blocks.sfml
@@ -27,7 +27,7 @@ NAME "Library Blocks"
 
 -- let f = Furnace { label: "my_furnace" }
 -- every 20 ticks do
---     expand smelt(f, ores, ingots)
+--     DO smelt(f, ores, ingots)
 -- end
 
 -- Note: Library blocks need to exist in-world with a disk containing definitions
diff --git a/src/main/resources/assets/sfm/template_programs/protocols_and_macros.sfml b/src/main/resources/assets/sfm/template_programs/protocols_and_macros.sfml
index a0b3a1991..c2dbe7514 100644
--- a/src/main/resources/assets/sfm/template_programs/protocols_and_macros.sfml
+++ b/src/main/resources/assets/sfm/template_programs/protocols_and_macros.sfml
@@ -35,8 +35,8 @@ end
 let furnace = Furnace { label: "furnaces" }
 let blast = BlastFurnace { label: "blast_furnaces" }
 
--- Use "expand" to invoke macros
+-- Use "DO" or "@" to invoke macros
 every 20 ticks do
-    expand smelt(furnace, ore_chest, ingot_chest)
-    expand smelt(blast, iron_ore, iron_ingots)
+    DO smelt(furnace, ore_chest, ingot_chest)
+    @smelt(blast, iron_ore, iron_ingots)
 end
diff --git a/src/test/java/ca/teamdman/sfml/SFMLTests.java b/src/test/java/ca/teamdman/sfml/SFMLTests.java
index e68f15091..bd1e9f941 100644
--- a/src/test/java/ca/teamdman/sfml/SFMLTests.java
+++ b/src/test/java/ca/teamdman/sfml/SFMLTests.java
@@ -1171,7 +1171,7 @@ macro transfer(source, dest)
                         end
 
                         every 20 ticks do
-                            expand transfer(chest_a, chest_b)
+                            DO transfer(chest_a, chest_b)
                         end
                         """
         );
@@ -1204,7 +1204,7 @@ macro smelt(machine: Smeltable, source, dest)
                         let furnace = Furnace { label: "furnaces" }
 
                         every 20 ticks do
-                            expand smelt(furnace, ore_chest, ingot_chest)
+                            DO smelt(furnace, ore_chest, ingot_chest)
                         end
                         """
         );
@@ -1216,7 +1216,7 @@ public void macroUnknownMacro() {
                 NAME "Unknown Macro Test"
 
                 every 20 ticks do
-                    expand unknown_macro(chest_a, chest_b)
+                    DO unknown_macro(chest_a, chest_b)
                 end
                 """;
         assertCompileErrorsPresent(input);
@@ -1233,7 +1233,7 @@ macro transfer(source, dest)
                 end
 
                 every 20 ticks do
-                    expand transfer(chest_a)
+                    DO transfer(chest_a)
                 end
                 """;
         assertCompileErrorsPresent(input);
@@ -1259,7 +1259,7 @@ macro smelt(machine: Smeltable)
                 let device = NonSmeltable { label: "devices" }
 
                 every 20 ticks do
-                    expand smelt(device)
+                    DO smelt(device)
                 end
                 """;
         assertCompileErrorsPresent(input);
@@ -1279,7 +1279,7 @@ macro transfer(x, y)
                 end
 
                 every 20 ticks do
-                    expand transfer(chest_a, chest_b)
+                    DO transfer(chest_a, chest_b)
                 end
                 """;
         assertCompileErrorsPresent(input);
@@ -1298,8 +1298,8 @@ macro process(source, dest)
                         end
 
                         every 20 ticks do
-                            expand process(chest_a, chest_b)
-                            expand process(chest_c, chest_d)
+                            @process(chest_a, chest_b)
+                            @process(chest_c, chest_d)
                         end
                         """
         );
@@ -1317,7 +1317,7 @@ macro limited_transfer(source, dest)
                         end
 
                         every 20 ticks do
-                            expand limited_transfer(chest_a, chest_b)
+                            DO limited_transfer(chest_a, chest_b)
                         end
                         """
         );
@@ -1357,7 +1357,7 @@ macro smelt(machine: Smeltable, ore_source, fuel_source, dest)
                         let furnace = Furnace { label: "furnaces" }
 
                         every 20 ticks do
-                            expand smelt(furnace, ore_chest, fuel_chest, result_chest)
+                            DO smelt(furnace, ore_chest, fuel_chest, result_chest)
                         end
                         """
         );
@@ -1374,7 +1374,7 @@ macro transfer(source, dest)
                 end
 
                 every 20 ticks do
-                    expand transfer(chest_a, chest_b)
+                    DO transfer(chest_a, chest_b)
                 end
                 """;
         assertNoCompileErrors(input);
@@ -1465,7 +1465,7 @@ macro smelt(machine: Smeltable, source, dest)
                         let furnace = Furnace { label: "furnaces" }
 
                         every 20 ticks do
-                            expand smelt(furnace, ore_chest, ingot_chest)
+                            DO smelt(furnace, ore_chest, ingot_chest)
                         end
                         """
         );
diff --git a/vscodeextension/super-factory-manager-language/syntaxes/SFML.g4 b/vscodeextension/super-factory-manager-language/syntaxes/SFML.g4
index ee6f13f95..868d21e41 100644
--- a/vscodeextension/super-factory-manager-language/syntaxes/SFML.g4
+++ b/vscodeextension/super-factory-manager-language/syntaxes/SFML.g4
@@ -7,10 +7,71 @@ grammar SFML;
     public boolean INCLUDE_UNUSED = false; // we want syntax highlighting to not break on unexpected tokens
 }
 
-program : name? trigger* EOF;
+program : name? library* protocolDefinition* structDefinition* macroDefinition* letStatement* trigger* EOF;
 
 name: NAME string ;
 
+//
+// LIBRARIES
+//
+
+library : USE LIBRARY string ;
+
+//
+// PROTOCOL DEFINITIONS
+//
+
+protocolDefinition : PROTOCOL identifier protocolBody END ;
+protocolBody : protocolField* ;
+protocolField : identifier COLON protocolFieldType ;
+protocolFieldType : SIDEQUALIFIER SLOTQUALIFIER    #SideAndSlotType
+                  | SIDEQUALIFIER                  #SideType
+                  | SLOTQUALIFIER                  #SlotType
+                  | LABEL                          #LabelType
+                  | RESOURCE                       #ResourceType
+                  | NUMBERTYPE                     #NumberType
+                  ;
+
+//
+// STRUCT DEFINITIONS
+//
+
+structDefinition : STRUCT identifier (COLON identifier (COMMA identifier)*)? structBody END ;
+structBody : structField* ;
+structField : identifier COLON structFieldValue ;
+structFieldValue : sidequalifier slotqualifier?
+                 | slotqualifier
+                 | label
+                 | resourceIdDisjunction
+                 | number
+                 ;
+
+//
+// MACRO DEFINITIONS
+//
+
+macroDefinition : MACRO identifier LPAREN macroParamList? RPAREN macroBody END ;
+macroParamList : macroParam (COMMA macroParam)* ;
+macroParam : identifier (COLON identifier)? ;
+macroBody : macroStatement* ;
+macroStatement : macroInputStatement
+               | macroOutputStatement
+               | macroIfStatement
+               | macroForgetStatement
+               ;
+macroInputStatement : INPUT macroResourceLimits? FROM EACH? macroLabelAccess ;
+macroOutputStatement : OUTPUT macroResourceLimits? TO EACH? macroLabelAccess ;
+macroIfStatement : IF boolexpr THEN macroBody (ELSE macroBody)? END ;
+macroForgetStatement : FORGET ;
+macroResourceLimits : resourceLimitList ;
+macroLabelAccess : identifier                                               #MacroParamLabelAccess
+                 | identifier USING identifier sidequalifier? slotqualifier? #MacroStructLabelAccess
+                 ;
+
+letStatement : LET identifier EQ_SYMBOL structInstantiation ;
+structInstantiation : identifier LBRACE structFieldAssignment (COMMA structFieldAssignment)* COMMA? RBRACE ;
+structFieldAssignment : identifier COLON structFieldValue ;
+
 //
 // TRIGGERS
 //
@@ -31,8 +92,13 @@ statement       : inputStatement
                 | outputStatement
                 | ifStatement
                 | forgetStatement
+                | expandStatement
                 ;
 
+expandStatement : (DO | AT) identifier LPAREN expandArgList? RPAREN ;
+expandArgList : expandArg (COMMA expandArg)* ;
+expandArg : identifier | string ;
+
 // IO STATEMENT
 forgetStatement : FORGET label? (COMMA label)* COMMA?;
 inputStatement  : INPUT inputResourceLimits? resourceExclusion? FROM EACH? labelAccess
@@ -142,7 +208,9 @@ setOp           : OVERALL
 //
 // IO HELPERS
 //
-labelAccess     : label (COMMA label)* roundrobin? sidequalifier? slotqualifier?;
+labelAccess     : label (COMMA label)* roundrobin? sidequalifier? slotqualifier?     #DirectLabelAccess
+                | identifier USING identifier sidequalifier? slotqualifier?        #StructLabelAccess
+                ;
 roundrobin      : ROUND ROBIN BY (LABEL | BLOCK);
 
 label           : (identifier)  #RawLabel
@@ -151,7 +219,7 @@ label           : (identifier)  #RawLabel
 
 emptyslots      : EMPTY (SLOTS | SLOT) IN ;
 
-identifier : (IDENTIFIER | REDSTONE | GLOBAL | SECOND | SECONDS | TOP | BOTTOM | LEFT | RIGHT | FRONT | BACK) ;
+identifier : (IDENTIFIER | REDSTONE | GLOBAL | SECOND | SECONDS | TOP | BOTTOM | LEFT | RIGHT | FRONT | BACK | INPUT | OUTPUT | LABEL | STRUCT | LET | USING | SLOT | SLOTS | SIDE | BLOCK | PROTOCOL | MACRO | DO | USE | LIBRARY | RESOURCE | SIDEQUALIFIER | SLOTQUALIFIER | NUMBERTYPE) ;
 
 // GENERAL
 string: STRING ;
@@ -253,6 +321,28 @@ DO              : D O ;
 END             : E N D ;
 NAME            : N A M E ;
 
+// STRUCT SYMBOLS
+STRUCT          : S T R U C T ;
+LET             : L E T ;
+USING           : U S I N G ;
+LBRACE          : '{' ;
+RBRACE          : '}' ;
+
+// PROTOCOL SYMBOLS
+PROTOCOL        : P R O T O C O L ;
+SIDEQUALIFIER   : S I D E Q U A L I F I E R ;
+SLOTQUALIFIER   : S L O T Q U A L I F I E R ;
+RESOURCE        : R E S O U R C E ;
+NUMBERTYPE      : N U M B E R ;
+
+// MACRO SYMBOLS
+MACRO           : M A C R O ;
+AT              : '@' ;
+
+// LIBRARY SYMBOLS
+USE             : U S E ;
+LIBRARY         : L I B R A R Y ;
+
 // GENERAL SYMBOLS
 // used by triggers and as a set operator
 EVERY           : E V E R Y ;

From 53eab73023a5f1e6d8a7bc094c4ce1e6a0094a84 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 12:24:19 +0100
Subject: [PATCH 19/33] style: rename ITEMS constant to items field

---
 .../blockentity/LibraryBlockEntity.java       | 32 +++++++++----------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
index c73a93ad3..8eae93352 100644
--- a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
+++ b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
@@ -52,7 +52,7 @@ public class LibraryBlockEntity extends BaseContainerBlockEntity {
 
     public static final int DISK_SLOT_COUNT = 10;
 
-    private final NonNullList<ItemStack> ITEMS = NonNullList.withSize(DISK_SLOT_COUNT, ItemStack.EMPTY);
+    private final NonNullList<ItemStack> items = NonNullList.withSize(DISK_SLOT_COUNT, ItemStack.EMPTY);
 
     public LibraryBlockEntity(BlockPos pos, BlockState state) {
         super(SFMBlockEntities.LIBRARY_BLOCK_ENTITY.get(), pos, state);
@@ -63,7 +63,7 @@ public LibraryBlockEntity(BlockPos pos, BlockState state) {
      * Disks without a NAME statement are shown with a placeholder name.
      */
     public List<LibraryContainerMenu.LibraryEntry> getLibraryEntries() {
-        return LibraryContainerMenu.extractLibraryEntries(this, DISK_SLOT_COUNT);
+        return LibraryContainerMenu.extractLibraryEntries(this, items.size());
     }
 
     /**
@@ -136,7 +136,7 @@ public LibraryDefinitions parseLibraryDefinitions(String source) {
     @Override
     protected void saveAdditional(CompoundTag tag) {
         super.saveAdditional(tag);
-        ContainerHelper.saveAllItems(tag, ITEMS);
+        ContainerHelper.saveAllItems(tag, items);
     }
 
     @Override
@@ -149,10 +149,10 @@ public void load(CompoundTag tag) {
             if (!legacySource.isEmpty()) {
                 ItemStack disk = new ItemStack(SFMItems.DISK_ITEM.get());
                 DiskItem.setProgram(disk, legacySource);
-                ITEMS.set(0, disk);
+                items.set(0, disk);
             }
         } else {
-            ContainerHelper.loadAllItems(tag, ITEMS);
+            ContainerHelper.loadAllItems(tag, items);
         }
     }
 
@@ -168,12 +168,12 @@ protected AbstractContainerMenu createMenu(int containerId, Inventory inventory)
 
     @Override
     public int getContainerSize() {
-        return ITEMS.size();
+        return items.size();
     }
 
     @Override
     public boolean isEmpty() {
-        for (ItemStack item : ITEMS) {
+        for (ItemStack item : items) {
             if (!item.isEmpty()) return false;
         }
         return true;
@@ -181,28 +181,28 @@ public boolean isEmpty() {
 
     @Override
     public ItemStack getItem(int slot) {
-        if (slot < 0 || slot >= ITEMS.size()) return ItemStack.EMPTY;
-        return ITEMS.get(slot);
+        if (slot < 0 || slot >= items.size()) return ItemStack.EMPTY;
+        return items.get(slot);
     }
 
     @Override
     public ItemStack removeItem(int slot, int amount) {
-        ItemStack result = ContainerHelper.removeItem(ITEMS, slot, amount);
+        ItemStack result = ContainerHelper.removeItem(items, slot, amount);
         setChanged();
         return result;
     }
 
     @Override
     public ItemStack removeItemNoUpdate(int slot) {
-        ItemStack result = ContainerHelper.takeItem(ITEMS, slot);
+        ItemStack result = ContainerHelper.takeItem(items, slot);
         setChanged();
         return result;
     }
 
     @Override
     public void setItem(int slot, ItemStack stack) {
-        if (slot < 0 || slot >= ITEMS.size()) return;
-        ITEMS.set(slot, stack);
+        if (slot < 0 || slot >= items.size()) return;
+        items.set(slot, stack);
         setChanged();
     }
 
@@ -223,7 +223,7 @@ public boolean stillValid(Player player) {
 
     @Override
     public void clearContent() {
-        ITEMS.clear();
+        items.clear();
     }
 
     // Client-side cache of disk mask for rendering
@@ -285,8 +285,8 @@ public void onDataPacket(net.minecraft.network.Connection net, ClientboundBlockE
      */
     private int computeDiskMask() {
         int mask = 0;
-        for (int i = 0; i < ITEMS.size(); i++) {
-            if (DiskItem.isValidDisk(ITEMS.get(i))) {
+        for (int i = 0; i < items.size(); i++) {
+            if (DiskItem.isValidDisk(items.get(i))) {
                 mask |= (1 << i);
             }
         }

From d9f26b349dd340c6323d12dbcce8ae02c8f909e2 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 12:24:40 +0100
Subject: [PATCH 20/33] fix: add debouncing for library changes and circular
 dependency detection

---
 .../sfm/common/cablenetwork/CableNetwork.java | 22 +++++++++++++
 .../java/ca/teamdman/sfml/ast/ASTBuilder.java | 32 +++++++++++++++----
 2 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
index 91b1ee50f..4c43fc4aa 100644
--- a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
+++ b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
@@ -37,6 +37,17 @@ public class CableNetwork {
      */
     private @Nullable LabelPositionHolder autoLabelCache = null;
 
+    /**
+     * Tracks the last game tick when manager notifications were sent.
+     * Used for debouncing rapid library changes.
+     */
+    private long lastNotificationTick = -1;
+
+    /**
+     * Minimum ticks between manager notifications to prevent excessive rebuilds.
+     */
+    private static final int NOTIFICATION_DEBOUNCE_TICKS = 5;
+
     public CableNetwork(Level level) {
         this.level = level;
         this.levelCapabilityCache = new SFMBlockCapabilityCacheForLevel(level);
@@ -281,6 +292,9 @@ public void invalidateAutoLabelCache() {
      * Invalidates the auto-label cache and notifies all managers on this network
      * to re-validate their programs. Call this when library blocks are added/removed
      * or when their contents change.
+     *
+     * Notifications are debounced to prevent excessive program rebuilds when
+     * multiple library changes occur in quick succession (e.g., inserting multiple disks).
      */
     public void invalidateAutoLabelsAndNotifyManagers() {
         // Get manager positions BEFORE invalidating the cache
@@ -290,6 +304,14 @@ public void invalidateAutoLabelsAndNotifyManagers() {
         // Now invalidate the cache
         autoLabelCache = null;
 
+        // Check debounce - skip notification if within debounce window
+        long currentTick = level.getGameTime();
+        if (lastNotificationTick >= 0 && currentTick - lastNotificationTick < NOTIFICATION_DEBOUNCE_TICKS) {
+            // Cache is already invalidated, managers will get fresh data on next tick
+            return;
+        }
+        lastNotificationTick = currentTick;
+
         // Notify all managers to re-validate their programs
         for (BlockPos pos : managerPositions) {
             if (level.getBlockEntity(pos) instanceof ManagerBlockEntity manager) {
diff --git a/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java b/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
index 953eedfb0..6e38558b7 100644
--- a/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
+++ b/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
@@ -38,6 +38,9 @@ public class ASTBuilder extends SFMLBaseVisitor<ASTNode> {
     /// Macro definitions indexed by name, populated during AST building
     private final Map<String, MacroDefinition> MACRO_DEFINITIONS = new HashMap<>();
 
+    /// Tracks libraries currently being resolved to detect circular dependencies
+    private final Set<String> librariesBeingResolved = new HashSet<>();
+
     /// Library resolver for resolving "use library" statements
     private LibraryResolver libraryResolver = LibraryResolver.NONE;
 
@@ -251,9 +254,23 @@ public Program visitProgram(SFMLParser.ProgramContext ctx) {
 
         // Resolve library definitions and import them before processing local definitions
         for (LibraryStatement libraryStmt : libraries) {
-            Optional<LibraryDefinitions> resolved = libraryResolver.resolve(libraryStmt.blockLabel());
+            String libraryName = libraryStmt.blockLabel();
+
+            // Check for circular dependency
+            if (librariesBeingResolved.contains(libraryName)) {
+                throw new IllegalArgumentException("Circular library dependency detected: " + libraryName);
+            }
+
+            librariesBeingResolved.add(libraryName);
+            Optional<LibraryDefinitions> resolved;
+            try {
+                resolved = libraryResolver.resolve(libraryName);
+            } finally {
+                librariesBeingResolved.remove(libraryName);
+            }
+
             if (resolved.isEmpty()) {
-                throw new IllegalArgumentException("Library '" + libraryStmt.blockLabel() + "' not found in cable network");
+                throw new IllegalArgumentException("Library '" + libraryName + "' not found in cable network");
             }
             LibraryDefinitions libDefs = resolved.get();
 
@@ -861,9 +878,14 @@ private OutputStatement expandMacroOutput(MacroOutputStatement macroOutput, Map<
     private LabelAccess resolveMacroLabelAccess(MacroLabelAccess macroAccess, Map<String, ExpandArgument> argMap) {
         ExpandArgument arg = argMap.get(macroAccess.parameterOrVariable());
 
+        // Early null check with clear error message
+        if (arg == null) {
+            throw new IllegalStateException("Unknown macro parameter: " + macroAccess.parameterOrVariable());
+        }
+
         if (macroAccess.isStructAccess()) {
             // This is a struct field access: param using field
-            if (arg == null || arg.isStringLiteral()) {
+            if (arg.isStringLiteral()) {
                 throw new IllegalStateException(
                         "Macro struct access requires a struct variable, got: " + macroAccess.parameterOrVariable()
                 );
@@ -917,10 +939,6 @@ private LabelAccess resolveMacroLabelAccess(MacroLabelAccess macroAccess, Map<St
             );
         } else {
             // This is a simple parameter reference
-            if (arg == null) {
-                throw new IllegalStateException("Unknown macro parameter: " + macroAccess.parameterOrVariable());
-            }
-
             Label label;
             if (arg.isStringLiteral()) {
                 // String literal becomes a label directly

From 2fe9c1ff3c9d7de43d692dacc4373b2c14d60512 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 12:25:10 +0100
Subject: [PATCH 21/33] feat: add library block crafting recipe

---
 .../sfm/datagen/SFMRecipesDatagen.java        | 13 +++++++
 .../9fb1092f32d4fcbf9e061ffd718d4ec689c6c95e  |  4 ++-
 .../sfm/advancements/recipes/sfm/library.json | 34 +++++++++++++++++++
 .../resources/data/sfm/recipes/library.json   | 22 ++++++++++++
 4 files changed, 72 insertions(+), 1 deletion(-)
 create mode 100644 src/generated/resources/data/sfm/advancements/recipes/sfm/library.json
 create mode 100644 src/generated/resources/data/sfm/recipes/library.json

diff --git a/src/datagen/java/ca/teamdman/sfm/datagen/SFMRecipesDatagen.java b/src/datagen/java/ca/teamdman/sfm/datagen/SFMRecipesDatagen.java
index f9589ebfd..a70ec23c1 100644
--- a/src/datagen/java/ca/teamdman/sfm/datagen/SFMRecipesDatagen.java
+++ b/src/datagen/java/ca/teamdman/sfm/datagen/SFMRecipesDatagen.java
@@ -5,6 +5,7 @@
 import ca.teamdman.sfm.common.registry.SFMBlocks;
 import ca.teamdman.sfm.common.registry.SFMItems;
 import ca.teamdman.sfm.common.registry.SFMRecipeSerializers;
+import ca.teamdman.sfm.common.util.SFMEnvironmentUtils;
 import ca.teamdman.sfm.common.util.SFMResourceLocation;
 import ca.teamdman.sfm.datagen.version_plumbing.MCVersionAgnosticRecipeDataGen;
 import net.minecraft.data.recipes.FinishedRecipe;
@@ -154,6 +155,18 @@ protected void populate(Consumer<FinishedRecipe> writer) {
                 .pattern("gxg")
                 .save(writer);
 
+        if (SFMEnvironmentUtils.isInIDE() && SFMBlocks.LIBRARY_BLOCK != null) {
+            beginShaped(SFMBlocks.LIBRARY_BLOCK.get(), 1)
+                    .define('M', SFMBlocks.MANAGER_BLOCK.get())
+                    .define('B', Blocks.BOOKSHELF)
+                    .define('L', Blocks.LECTERN)
+                    .unlockedBy("has_manager", RecipeProvider.has(SFMBlocks.MANAGER_BLOCK.get()))
+                    .pattern("MBM")
+                    .pattern("BLB")
+                    .pattern("MBM")
+                    .save(writer);
+        }
+
         addPrintingPressRecipe(
                 writer,
                 SFMResourceLocation.fromSFMPath("written_book_copy"),
diff --git a/src/generated/resources/.cache/9fb1092f32d4fcbf9e061ffd718d4ec689c6c95e b/src/generated/resources/.cache/9fb1092f32d4fcbf9e061ffd718d4ec689c6c95e
index 0e80505b3..84879d3bd 100644
--- a/src/generated/resources/.cache/9fb1092f32d4fcbf9e061ffd718d4ec689c6c95e
+++ b/src/generated/resources/.cache/9fb1092f32d4fcbf9e061ffd718d4ec689c6c95e
@@ -1,4 +1,4 @@
-// 1.19.2	2025-11-09T12:56:10.8084432	Recipes
+// 1.19.2	2026-01-25T11:49:16.7151191	Recipes
 7ded111f9e17f19c22e228ed71a142b4cb9ec527 data/minecraft/advancements/recipes/sfm/tunnelled_manager_horizontal.json
 da2d621c83e62b6385405f9d13afb961b33c50a9 data/minecraft/advancements/recipes/sfm/tunnelled_manager_vertical.json
 220658ab093bcf17e9432b2a8baf08809a7c6434 data/minecraft/advancements/recipes/sfm/uncraft_tunnelled_manager.json
@@ -11,6 +11,7 @@ da2d621c83e62b6385405f9d13afb961b33c50a9 data/minecraft/advancements/recipes/sfm
 3812a02ebe30dcd7536c329803d6a65d05a14800 data/sfm/advancements/recipes/sfm/disk.json
 b725fc4de1a90aaf2d01b0f35a1ce27f224c28d7 data/sfm/advancements/recipes/sfm/fancy_cable.json
 5ab1a54cb2fe6bb9413bddf645feefb5cf9224cd data/sfm/advancements/recipes/sfm/fancy_to_cable.json
+105d00768e69b0fe1ac995e483540239921560d6 data/sfm/advancements/recipes/sfm/library.json
 6c7cda7b36500f3d8a4dd623c9dd6bfd14d301b4 data/sfm/advancements/recipes/sfm/manager.json
 5d5c0ab9485456aafdf9c693f00786b52d883e6b data/sfm/advancements/recipes/sfm/network_tool.json
 90144588e0c1cb7857f8cc7ec6a73ec36485080e data/sfm/advancements/recipes/sfm/printing_press.json
@@ -22,6 +23,7 @@ ce43b2a22f3ad72b5360ec9203dbfb1e91a4a671 data/sfm/recipes/disk.json
 86b45396d6e685d9f816a6da3434eb5d7f49f178 data/sfm/recipes/enchanted_book_copy.json
 f70a61a222119968c8534f2735fa3294e4de521b data/sfm/recipes/fancy_cable.json
 33c5e1c41f605a33864e706e0a6dfb48b521d6ec data/sfm/recipes/fancy_to_cable.json
+0e8e9115333e425787d46928b8af979aab9a34fd data/sfm/recipes/library.json
 306641bbc2f89d40e9dc83cf126ee696ecc40300 data/sfm/recipes/manager.json
 4432751f9842cae951f8b9dc8e405317ea4dc08f data/sfm/recipes/map_copy.json
 7c201e42b5e054c7d1c2844e5b2647ef3b66ad0d data/sfm/recipes/network_tool.json
diff --git a/src/generated/resources/data/sfm/advancements/recipes/sfm/library.json b/src/generated/resources/data/sfm/advancements/recipes/sfm/library.json
new file mode 100644
index 000000000..fa8e2c604
--- /dev/null
+++ b/src/generated/resources/data/sfm/advancements/recipes/sfm/library.json
@@ -0,0 +1,34 @@
+{
+  "parent": "minecraft:recipes/root",
+  "criteria": {
+    "has_manager": {
+      "conditions": {
+        "items": [
+          {
+            "items": [
+              "sfm:manager"
+            ]
+          }
+        ]
+      },
+      "trigger": "minecraft:inventory_changed"
+    },
+    "has_the_recipe": {
+      "conditions": {
+        "recipe": "sfm:library"
+      },
+      "trigger": "minecraft:recipe_unlocked"
+    }
+  },
+  "requirements": [
+    [
+      "has_manager",
+      "has_the_recipe"
+    ]
+  ],
+  "rewards": {
+    "recipes": [
+      "sfm:library"
+    ]
+  }
+}
\ No newline at end of file
diff --git a/src/generated/resources/data/sfm/recipes/library.json b/src/generated/resources/data/sfm/recipes/library.json
new file mode 100644
index 000000000..5c3c47ab1
--- /dev/null
+++ b/src/generated/resources/data/sfm/recipes/library.json
@@ -0,0 +1,22 @@
+{
+  "type": "minecraft:crafting_shaped",
+  "key": {
+    "B": {
+      "item": "minecraft:bookshelf"
+    },
+    "L": {
+      "item": "minecraft:lectern"
+    },
+    "M": {
+      "item": "sfm:manager"
+    }
+  },
+  "pattern": [
+    "MBM",
+    "BLB",
+    "MBM"
+  ],
+  "result": {
+    "item": "sfm:library"
+  }
+}
\ No newline at end of file

From dbfc900f16bf5850c3a93a90505f5d61124c9a8e Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 13:16:13 +0100
Subject: [PATCH 22/33] feat: enable USE statements in library disks and error
 display

---
 .../sfm/client/screen/LibraryScreen.java      |  47 ++++-
 .../blockentity/LibraryBlockEntity.java       | 176 +++++++++++++-----
 .../blockentity/ManagerBlockEntity.java       |  45 +----
 .../sfm/common/cablenetwork/CableNetwork.java | 100 +++++++++-
 .../containermenu/LibraryContainerMenu.java   |  16 +-
 ...erverboundLibraryDiskSetProgramPacket.java |   5 +-
 6 files changed, 293 insertions(+), 96 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java b/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
index 346ad7351..fdf2716e3 100644
--- a/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
+++ b/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
@@ -45,6 +45,12 @@ public class LibraryScreen extends AbstractContainerScreen<LibraryContainerMenu>
     private static final int TEXT_HOVER = 0xFFFFD080;
     private static final int TEXT_DIM = 0xFF806020;
 
+    // Error/Warning colors (red phosphor style)
+    private static final int TEXT_ERROR = 0xFFFF4040;
+    private static final int TEXT_ERROR_DIM = 0xFFCC3030;
+    private static final int ERROR_GLOW = 0x40FF2020;
+    private static final int TEXT_WARNING = 0xFFFFCC40;
+
     // Effects
     private static final int CURSOR_GLOW = 0x30FFB84D;
 
@@ -155,21 +161,50 @@ public void render(
                 boolean hovered = mx >= screenX + 3 && mx <= screenRight - 3
                         && my >= contentY - 1 && my <= contentY + font.lineHeight + 1;
 
+                // Determine colors based on error/warning status
+                int bgGlow;
+                int textColor;
+                int statusColor;
+                String statusIndicator = "";
+
+                if (entry.hasErrors()) {
+                    // Error state - red phosphor effect
+                    bgGlow = hovered ? ERROR_GLOW : 0x20FF2020;
+                    textColor = hovered ? TEXT_ERROR : TEXT_ERROR_DIM;
+                    statusColor = TEXT_ERROR;
+                    statusIndicator = "!";
+                } else if (entry.hasWarnings()) {
+                    // Warning state - yellow/amber
+                    bgGlow = hovered ? CURSOR_GLOW : 0x20FFCC40;
+                    textColor = hovered ? TEXT_WARNING : TEXT_NORMAL;
+                    statusColor = TEXT_WARNING;
+                    statusIndicator = "?";
+                } else {
+                    // Normal state
+                    bgGlow = CURSOR_GLOW;
+                    textColor = hovered ? TEXT_HOVER : TEXT_NORMAL;
+                    statusColor = TEXT_DIM;
+                    statusIndicator = "";
+                }
+
                 if (hovered) {
                     hoveredLibraryEntry = i;
                     // Draw hover glow background
-                    fill(poseStack, screenX + 3, contentY - 1, screenRight - 3, contentY + font.lineHeight + 1, CURSOR_GLOW);
+                    fill(poseStack, screenX + 3, contentY - 1, screenRight - 3, contentY + font.lineHeight + 1, bgGlow);
+                } else if (entry.hasErrors()) {
+                    // Always show subtle error background glow
+                    fill(poseStack, screenX + 3, contentY - 1, screenRight - 3, contentY + font.lineHeight + 1, bgGlow);
                 }
 
                 // Cursor indicator and library name
                 String cursor = hovered ? "> " : "  ";
-                int color = hovered ? TEXT_HOVER : TEXT_NORMAL;
-                font.drawShadow(poseStack, cursor + entry.name(), textX, contentY, color);
+                font.drawShadow(poseStack, cursor + entry.name(), textX, contentY, textColor);
 
-                // Slot number right-aligned
-                String slotText = "[" + (entry.slotIndex()) + "]";
+                // Status indicator (! for error, ? for warning) and slot number right-aligned
+                String slotText = statusIndicator + "[" + (entry.slotIndex()) + "]";
                 int slotWidth = font.width(slotText);
-                font.drawShadow(poseStack, slotText, screenRight - 6 - slotWidth, contentY, TEXT_DIM);
+                font.drawShadow(poseStack, slotText, screenRight - 6 - slotWidth, contentY,
+                        statusIndicator.isEmpty() ? TEXT_DIM : statusColor);
 
                 contentY += font.lineHeight + 3;
 
diff --git a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
index 8eae93352..b704b6c27 100644
--- a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
+++ b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
@@ -1,7 +1,5 @@
 package ca.teamdman.sfm.common.blockentity;
 
-import ca.teamdman.langs.SFMLLexer;
-import ca.teamdman.langs.SFMLParser;
 import ca.teamdman.sfm.common.cablenetwork.CableNetwork;
 import ca.teamdman.sfm.common.cablenetwork.CableNetworkManager;
 import ca.teamdman.sfm.common.containermenu.LibraryContainerMenu;
@@ -10,32 +8,30 @@
 import ca.teamdman.sfm.common.registry.SFMBlockEntities;
 import ca.teamdman.sfm.common.registry.SFMItems;
 import ca.teamdman.sfm.common.util.SFMContainerUtil;
-import ca.teamdman.sfml.ast.ASTBuilder;
-import ca.teamdman.sfml.ast.MacroDefinition;
 import ca.teamdman.sfml.ast.Program;
-import ca.teamdman.sfml.ast.ProtocolDefinition;
-import ca.teamdman.sfml.ast.StructDefinition;
 import ca.teamdman.sfml.program_builder.LibraryDefinitions;
+import ca.teamdman.sfml.program_builder.LibraryResolver;
+import ca.teamdman.sfml.program_builder.ProgramBuilder;
 import net.minecraft.core.BlockPos;
 import net.minecraft.core.NonNullList;
 import net.minecraft.nbt.CompoundTag;
 import net.minecraft.network.chat.Component;
+import net.minecraft.network.protocol.Packet;
+import net.minecraft.network.protocol.game.ClientGamePacketListener;
+import net.minecraft.network.protocol.game.ClientboundBlockEntityDataPacket;
 import net.minecraft.world.ContainerHelper;
 import net.minecraft.world.entity.player.Inventory;
 import net.minecraft.world.entity.player.Player;
 import net.minecraft.world.inventory.AbstractContainerMenu;
 import net.minecraft.world.item.ItemStack;
-import net.minecraft.network.protocol.Packet;
-import net.minecraft.network.protocol.game.ClientGamePacketListener;
-import net.minecraft.network.protocol.game.ClientboundBlockEntityDataPacket;
 import net.minecraft.world.level.block.entity.BaseContainerBlockEntity;
 import net.minecraft.world.level.block.state.BlockState;
-import org.antlr.v4.runtime.CharStreams;
-import org.antlr.v4.runtime.CommonTokenStream;
 import org.jetbrains.annotations.Nullable;
 
-import java.util.ArrayList;
+import java.util.HashSet;
 import java.util.List;
+import java.util.Optional;
+import java.util.Set;
 
 /**
  * Block entity for library blocks that store disks containing SFML definitions.
@@ -68,11 +64,27 @@ public List<LibraryContainerMenu.LibraryEntry> getLibraryEntries() {
 
     /**
      * Gets library definitions from a disk with a matching NAME.
+     * This overload uses no library resolver (for backward compatibility).
      *
      * @param libraryName The name to search for
      * @return The parsed definitions, or null if not found
      */
     public @Nullable LibraryDefinitions getDefinitionsForLibrary(String libraryName) {
+        return getDefinitionsForLibrary(libraryName, LibraryResolver.NONE);
+    }
+
+    /**
+     * Gets library definitions from a disk with a matching NAME.
+     * Supports resolving USE statements within the library disk.
+     *
+     * @param libraryName The name to search for
+     * @param resolver The library resolver for resolving USE statements (handles circular dependency tracking)
+     * @return The parsed definitions, or null if not found
+     */
+    public @Nullable LibraryDefinitions getDefinitionsForLibrary(
+            String libraryName,
+            LibraryResolver resolver
+    ) {
         for (int i = 0; i < DISK_SLOT_COUNT; i++) {
             ItemStack disk = getItem(i);
             if (!DiskItem.isValidDisk(disk)) continue;
@@ -81,7 +93,7 @@ public List<LibraryContainerMenu.LibraryEntry> getLibraryEntries() {
             String name = DiskItem.extractName(source);
 
             if (libraryName.equals(name)) {
-                return parseLibraryDefinitions(source);
+                return parseLibraryDefinitions(source, resolver);
             }
         }
         return null;
@@ -89,48 +101,100 @@ public List<LibraryContainerMenu.LibraryEntry> getLibraryEntries() {
 
     /**
      * Parses library definitions from source code.
-     * Extracts only protocols, structs, and macros (ignores triggers/let statements).
+     * Extracts protocols, structs, and macros, including those imported via USE statements.
+     *
+     * @param source The source code to parse
+     * @param resolver The library resolver for resolving USE statements (handles circular dependency tracking)
+     * @return The parsed library definitions
      */
-    public LibraryDefinitions parseLibraryDefinitions(String source) {
-        SFMLLexer lexer = new SFMLLexer(CharStreams.fromString(source));
-        CommonTokenStream tokens = new CommonTokenStream(lexer);
-        SFMLParser parser = new SFMLParser(tokens);
-
-        // Set up error capturing
-        List<String> errors = new ArrayList<>();
-        lexer.removeErrorListeners();
-        parser.removeErrorListeners();
-        Program.ListErrorListener listener = new Program.ListErrorListener(errors);
-        lexer.addErrorListener(listener);
-        parser.addErrorListener(listener);
-
-        SFMLParser.ProgramContext context = parser.program();
-        if (!errors.isEmpty()) {
-            throw new IllegalArgumentException(String.join(", ", errors));
+    public LibraryDefinitions parseLibraryDefinitions(
+            String source,
+            LibraryResolver resolver
+    ) {
+        // Use ProgramBuilder to parse the full program, including USE statements
+        var buildResult = new ProgramBuilder(source)
+                .withLibraryResolver(resolver)
+                .useCache(false)
+                .build();
+
+        // Check for errors
+        if (!buildResult.metadata().errors().isEmpty()) {
+            String errorMsg = buildResult.metadata().errors().stream()
+                    .map(e -> {
+                        Object[] args = e.getArgs();
+                        if (args.length > 0) {
+                            return String.valueOf(args[0]);
+                        }
+                        return e.getKey();
+                    })
+                    .reduce((a, b) -> a + ", " + b)
+                    .orElse("Unknown error");
+            throw new IllegalArgumentException(errorMsg);
         }
 
-        // Use ASTBuilder to parse definitions
-        ASTBuilder builder = new ASTBuilder();
-
-        // Parse protocol definitions
-        List<ProtocolDefinition> protocols = new ArrayList<>();
-        for (SFMLParser.ProtocolDefinitionContext protoCtx : context.protocolDefinition()) {
-            protocols.add(builder.visitProtocolDefinition(protoCtx));
+        Program program = buildResult.program();
+        if (program == null) {
+            throw new IllegalArgumentException("Failed to parse library definitions");
         }
 
-        // Parse struct definitions
-        List<StructDefinition> structs = new ArrayList<>();
-        for (SFMLParser.StructDefinitionContext structCtx : context.structDefinition()) {
-            structs.add(builder.visitStructDefinition(structCtx));
+        // Extract definitions from the parsed program (includes imported definitions)
+        return new LibraryDefinitions(
+                program.protocolDefinitions(),
+                program.structDefinitions(),
+                program.macroDefinitions()
+        );
+    }
+
+    /**
+     * Creates a library resolver for use when compiling disks in this library block.
+     * First checks disks in this library block, then checks other libraries on the network.
+     *
+     * @return A library resolver that can find libraries in this block and on the network
+     */
+    public LibraryResolver createLibraryResolver() {
+        if (level == null) {
+            // Fallback: only resolve from this library block's disks
+            return createLocalLibraryResolver(new HashSet<>());
         }
 
-        // Parse macro definitions
-        List<MacroDefinition> macros = new ArrayList<>();
-        for (SFMLParser.MacroDefinitionContext macroCtx : context.macroDefinition()) {
-            macros.add(builder.visitMacroDefinition(macroCtx));
+        // Find the cable network this library is adjacent to
+        Optional<CableNetwork> networkOpt = CableNetworkManager.getNetworksForLevel(level)
+                .filter(network -> network.isAdjacentToCable(worldPosition))
+                .findFirst();
+
+        if (networkOpt.isEmpty()) {
+            // Not connected to network: only resolve from this library block's disks
+            return createLocalLibraryResolver(new HashSet<>());
         }
 
-        return new LibraryDefinitions(protocols, structs, macros);
+        // Connected to network: use the network's resolver (which includes all library blocks)
+        return networkOpt.get().createLibraryResolver();
+    }
+
+    /**
+     * Creates a library resolver that only resolves from this library block's disks.
+     * Used when not connected to a cable network.
+     *
+     * @param librariesBeingResolved Shared set for tracking circular dependencies
+     * @return A library resolver for this block only
+     */
+    private LibraryResolver createLocalLibraryResolver(Set<String> librariesBeingResolved) {
+        return libraryName -> {
+            // Check for circular dependency
+            if (librariesBeingResolved.contains(libraryName)) {
+                throw new IllegalArgumentException("Circular library dependency detected: " + libraryName);
+            }
+
+            librariesBeingResolved.add(libraryName);
+            try {
+                // Create a nested resolver for any USE statements in the resolved library
+                LibraryResolver nestedResolver = createLocalLibraryResolver(librariesBeingResolved);
+                LibraryDefinitions defs = getDefinitionsForLibrary(libraryName, nestedResolver);
+                return Optional.ofNullable(defs);
+            } finally {
+                librariesBeingResolved.remove(libraryName);
+            }
+        };
     }
 
     @Override
@@ -242,7 +306,7 @@ public void setChanged() {
 
     /**
      * Notifies any cable networks adjacent to this library block that the library
-     * configuration has changed, causing managers to re-validate their programs.
+     * configuration has changed, causing managers and other library disks to recompile.
      */
     private void notifyNetworkLibraryChanged() {
         if (level == null || level.isClientSide()) return;
@@ -250,7 +314,23 @@ private void notifyNetworkLibraryChanged() {
         // Find networks adjacent to this library block and notify them
         CableNetworkManager.getNetworksForLevel(level)
                 .filter(network -> network.isAdjacentToCable(worldPosition))
-                .forEach(CableNetwork::invalidateAutoLabelsAndNotifyManagers);
+                .forEach(CableNetwork::invalidateAutoLabelsAndNotifyDependents);
+    }
+
+    /**
+     * Recompiles all disks in this library block.
+     * Called when a library on the network changes to update circular dependency errors.
+     */
+    public void recompileAllDisks() {
+        if (level == null || level.isClientSide()) return;
+
+        var resolver = createLibraryResolver();
+        for (int i = 0; i < DISK_SLOT_COUNT; i++) {
+            ItemStack disk = getItem(i);
+            if (!DiskItem.isValidDisk(disk)) continue;
+
+            DiskItem.compileAndUpdateErrorsAndWarnings(disk, null, true, resolver);
+        }
     }
 
     // Client sync methods for BlockEntityRenderer
diff --git a/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java b/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java
index 84d9f0a44..3c207b457 100644
--- a/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java
+++ b/src/main/java/ca/teamdman/sfm/common/blockentity/ManagerBlockEntity.java
@@ -23,7 +23,6 @@
 import ca.teamdman.sfm.common.timing.SFMInstant;
 import ca.teamdman.sfm.common.util.SFMContainerUtil;
 import ca.teamdman.sfml.ast.Program;
-import ca.teamdman.sfml.program_builder.LibraryDefinitions;
 import ca.teamdman.sfml.program_builder.LibraryResolver;
 import com.google.common.base.Joiner;
 import net.minecraft.ChatFormatting;
@@ -379,44 +378,20 @@ public void rebuildProgramAndUpdateDisk() {
 
     /**
      * Creates a library resolver that finds definitions from library blocks on the cable network.
-     * Uses the auto-discovered label cache for O(1) library block lookup.
-     * The resolver:
-     * 1. Gets the cable network connected to this manager
-     * 2. Uses the auto-label cache to get all library block positions
-     * 3. For each library block, checks disk slots for a matching NAME
-     * 4. Returns the parsed definitions from the first matching disk
+     * Delegates to the network's resolver implementation.
      */
     public LibraryResolver createLibraryResolver() {
-        return libraryName -> {
-            if (level == null) {
-                return Optional.empty();
-            }
-
-            // Get the cable network for this manager
-            Optional<CableNetwork> networkOpt = CableNetworkManager.getOrRegisterNetworkFromManagerPosition(this);
-            if (networkOpt.isEmpty()) {
-                return Optional.empty();
-            }
-            CableNetwork network = networkOpt.get();
-
-            // O(1) lookup for all library positions via auto-discovered labels
-            Set<BlockPos> libraryPositions = network.getOrRebuildAutoLabels()
-                    .getPositions(LibraryBlockEntity.LIBRARY_LABEL);
-
-            // O(N) scan of libraries where N is the number of library blocks (typically small)
-            for (BlockPos pos : libraryPositions) {
-                if (!(level.getBlockEntity(pos) instanceof LibraryBlockEntity library)) {
-                    continue;
-                }
+        if (level == null) {
+            return LibraryResolver.NONE;
+        }
 
-                LibraryDefinitions defs = library.getDefinitionsForLibrary(libraryName);
-                if (defs != null) {
-                    return Optional.of(defs);
-                }
-            }
+        // Get the cable network for this manager
+        Optional<CableNetwork> networkOpt = CableNetworkManager.getOrRegisterNetworkFromManagerPosition(this);
+        if (networkOpt.isEmpty()) {
+            return LibraryResolver.NONE;
+        }
 
-            return Optional.empty();
-        };
+        return networkOpt.get().createLibraryResolver();
     }
 
     @Override
diff --git a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
index 4c43fc4aa..406234aaa 100644
--- a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
+++ b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
@@ -3,6 +3,8 @@
 import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
 import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
 import ca.teamdman.sfm.common.label.LabelPositionHolder;
+import ca.teamdman.sfml.program_builder.LibraryDefinitions;
+import ca.teamdman.sfml.program_builder.LibraryResolver;
 import ca.teamdman.sfm.common.capability.SFMBlockCapabilityDiscovery;
 import ca.teamdman.sfm.common.capability.SFMBlockCapabilityKind;
 import ca.teamdman.sfm.common.capability.SFMBlockCapabilityResult;
@@ -20,7 +22,9 @@
 import org.jetbrains.annotations.Nullable;
 
 import java.util.ArrayList;
+import java.util.HashSet;
 import java.util.List;
+import java.util.Optional;
 import java.util.Set;
 import java.util.stream.Stream;
 
@@ -290,8 +294,7 @@ public void invalidateAutoLabelCache() {
 
     /**
      * Invalidates the auto-label cache and notifies all managers on this network
-     * to re-validate their programs. Call this when library blocks are added/removed
-     * or when their contents change.
+     * to re-validate their programs. Call this when library blocks are added/removed.
      *
      * Notifications are debounced to prevent excessive program rebuilds when
      * multiple library changes occur in quick succession (e.g., inserting multiple disks).
@@ -320,6 +323,46 @@ public void invalidateAutoLabelsAndNotifyManagers() {
         }
     }
 
+    /**
+     * Invalidates the auto-label cache and notifies all managers and library blocks
+     * on this network to recompile. Call this when library disk contents change.
+     *
+     * Notifications are debounced to prevent excessive program rebuilds when
+     * multiple library changes occur in quick succession.
+     */
+    public void invalidateAutoLabelsAndNotifyDependents() {
+        // Get positions BEFORE invalidating the cache
+        Set<BlockPos> managerPositions = getOrRebuildAutoLabels()
+                .getPositions(ManagerBlockEntity.MANAGER_LABEL);
+        Set<BlockPos> libraryPositions = getOrRebuildAutoLabels()
+                .getPositions(LibraryBlockEntity.LIBRARY_LABEL);
+
+        // Now invalidate the cache
+        autoLabelCache = null;
+
+        // Check debounce - skip notification if within debounce window
+        long currentTick = level.getGameTime();
+        if (lastNotificationTick >= 0 && currentTick - lastNotificationTick < NOTIFICATION_DEBOUNCE_TICKS) {
+            // Cache is already invalidated, dependents will get fresh data on next tick
+            return;
+        }
+        lastNotificationTick = currentTick;
+
+        // Notify all managers to re-validate their programs
+        for (BlockPos pos : managerPositions) {
+            if (level.getBlockEntity(pos) instanceof ManagerBlockEntity manager) {
+                manager.rebuildProgramAndUpdateDisk();
+            }
+        }
+
+        // Notify all library blocks to recompile their disks
+        for (BlockPos pos : libraryPositions) {
+            if (level.getBlockEntity(pos) instanceof LibraryBlockEntity library) {
+                library.recompileAllDisks();
+            }
+        }
+    }
+
     /**
      * Discover what networks would exist if this network did not have a cable at {@code cablePos}.
      *
@@ -341,4 +384,57 @@ protected List<CableNetwork> withoutCable(BlockPos cablePos) {
         }
         return branches;
     }
+
+    /**
+     * Creates a library resolver that finds definitions from library blocks on this cable network.
+     * Uses the auto-discovered label cache for O(1) library block lookup.
+     *
+     * @return A library resolver for this network
+     */
+    public LibraryResolver createLibraryResolver() {
+        return createLibraryResolver(new HashSet<>());
+    }
+
+    /**
+     * Creates a library resolver that finds definitions from library blocks on this cable network.
+     * Uses the auto-discovered label cache for O(1) library block lookup.
+     * Supports tracking circular dependencies across nested library resolutions.
+     *
+     * @param librariesBeingResolved Shared set for tracking circular dependencies across resolution calls
+     * @return A library resolver for this network
+     */
+    public LibraryResolver createLibraryResolver(Set<String> librariesBeingResolved) {
+        return libraryName -> {
+            // Check for circular dependency before resolving
+            if (librariesBeingResolved.contains(libraryName)) {
+                throw new IllegalArgumentException("Circular library dependency detected: " + libraryName);
+            }
+
+            // O(1) lookup for all library positions via auto-discovered labels
+            Set<BlockPos> libraryPositions = getOrRebuildAutoLabels()
+                    .getPositions(LibraryBlockEntity.LIBRARY_LABEL);
+
+            // Track this library to detect circular dependencies
+            librariesBeingResolved.add(libraryName);
+            try {
+                // O(N) scan of libraries where N is the number of library blocks (typically small)
+                for (BlockPos pos : libraryPositions) {
+                    if (!(level.getBlockEntity(pos) instanceof LibraryBlockEntity library)) {
+                        continue;
+                    }
+
+                    // Create a nested resolver that shares the circular dependency tracking
+                    LibraryResolver nestedResolver = createLibraryResolver(librariesBeingResolved);
+                    LibraryDefinitions defs = library.getDefinitionsForLibrary(libraryName, nestedResolver);
+                    if (defs != null) {
+                        return Optional.of(defs);
+                    }
+                }
+            } finally {
+                librariesBeingResolved.remove(libraryName);
+            }
+
+            return Optional.empty();
+        };
+    }
 }
diff --git a/src/main/java/ca/teamdman/sfm/common/containermenu/LibraryContainerMenu.java b/src/main/java/ca/teamdman/sfm/common/containermenu/LibraryContainerMenu.java
index 3c10c08f8..437936e69 100644
--- a/src/main/java/ca/teamdman/sfm/common/containermenu/LibraryContainerMenu.java
+++ b/src/main/java/ca/teamdman/sfm/common/containermenu/LibraryContainerMenu.java
@@ -33,9 +33,9 @@ public class LibraryContainerMenu extends AbstractContainerMenu {
     private static final int PLAYER_HOTBAR_Y = 142;
 
     /**
-     * Record to track library name and its slot index.
+     * Record to track library name, slot index, and error/warning status.
      */
-    public record LibraryEntry(String name, int slotIndex) {}
+    public record LibraryEntry(String name, int slotIndex, boolean hasErrors, boolean hasWarnings) {}
 
     /**
      * Extracts library entries from a container's disk slots.
@@ -56,7 +56,9 @@ public static List<LibraryEntry> extractLibraryEntries(Container container, int
             if (name == null || name.isEmpty()) {
                 name = "(unnamed)";
             }
-            entries.add(new LibraryEntry(name, i));
+            boolean hasErrors = !DiskItem.getErrors(disk).isEmpty();
+            boolean hasWarnings = !DiskItem.getWarnings(disk).isEmpty();
+            entries.add(new LibraryEntry(name, i, hasErrors, hasWarnings));
         }
         return entries;
     }
@@ -146,7 +148,11 @@ private static List<LibraryEntry> readLibraryEntries(FriendlyByteBuf buf) {
         int count = buf.readVarInt();
         List<LibraryEntry> entries = new ArrayList<>(count);
         for (int i = 0; i < count; i++) {
-            entries.add(new LibraryEntry(buf.readUtf(256), buf.readVarInt()));
+            String name = buf.readUtf(256);
+            int slotIndex = buf.readVarInt();
+            boolean hasErrors = buf.readBoolean();
+            boolean hasWarnings = buf.readBoolean();
+            entries.add(new LibraryEntry(name, slotIndex, hasErrors, hasWarnings));
         }
         return entries;
     }
@@ -156,6 +162,8 @@ private static void writeLibraryEntries(List<LibraryEntry> entries, FriendlyByte
         for (LibraryEntry entry : entries) {
             buf.writeUtf(entry.name(), 256);
             buf.writeVarInt(entry.slotIndex());
+            buf.writeBoolean(entry.hasErrors());
+            buf.writeBoolean(entry.hasWarnings());
         }
     }
 
diff --git a/src/main/java/ca/teamdman/sfm/common/net/ServerboundLibraryDiskSetProgramPacket.java b/src/main/java/ca/teamdman/sfm/common/net/ServerboundLibraryDiskSetProgramPacket.java
index 332808481..40256c06b 100644
--- a/src/main/java/ca/teamdman/sfm/common/net/ServerboundLibraryDiskSetProgramPacket.java
+++ b/src/main/java/ca/teamdman/sfm/common/net/ServerboundLibraryDiskSetProgramPacket.java
@@ -81,7 +81,10 @@ public void handle(
 
             // Update the disk's program
             DiskItem.setProgram(disk, msg.programString);
-            DiskItem.compileAndUpdateErrorsAndWarnings(disk, null, true);
+
+            // Create a library resolver so USE statements can resolve other libraries on the network
+            var libraryResolver = library.createLibraryResolver();
+            DiskItem.compileAndUpdateErrorsAndWarnings(disk, null, true, libraryResolver);
             DiskItem.pruneIfDefault(disk);
             library.setChanged();
 

From f64f993baff7fe0ea2658d01a49f4b8f09319eb9 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 14:27:49 +0100
Subject: [PATCH 23/33] feat: improve library block visuals with pulsing
 indicators and server rack textures

---
 .../render/LibraryBlockEntityRenderer.java    | 241 ++++++++++++++++--
 .../blockentity/LibraryBlockEntity.java       |  60 +++++
 .../sfm/textures/block/library_back.png       | Bin 119 -> 791 bytes
 .../assets/sfm/textures/block/library_bot.png | Bin 158 -> 1019 bytes
 .../sfm/textures/block/library_front.png      | Bin 140 -> 930 bytes
 .../sfm/textures/block/library_side.png       | Bin 148 -> 916 bytes
 .../assets/sfm/textures/block/library_top.png | Bin 160 -> 990 bytes
 7 files changed, 274 insertions(+), 27 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java b/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java
index 9986b5965..472c0f0a8 100644
--- a/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java
+++ b/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java
@@ -11,29 +11,76 @@
 import net.minecraft.client.renderer.blockentity.BlockEntityRenderer;
 import net.minecraft.client.renderer.blockentity.BlockEntityRendererProvider;
 import net.minecraft.core.Direction;
+import net.minecraft.world.level.Level;
 
 /**
  * Renders disk slot indicators on the front face of the library block.
- * Shows amber lights for occupied slots, matching their physical positions.
+ * Shows colored lights for occupied slots: green (normal), yellow (warnings), red (errors).
+ * Indicators pulse with speed/intensity based on status.
  */
 public class LibraryBlockEntityRenderer implements BlockEntityRenderer<LibraryBlockEntity> {
 
-    // Amber phosphor color (matching the UI palette)
-    private static final float AMBER_R = 204f / 255f;
-    private static final float AMBER_G = 150f / 255f;
-    private static final float AMBER_B = 64f / 255f;
+    // Indicator light colors
+    // Normal state: Green
+    private static final float NORMAL_R = 64f / 255f;
+    private static final float NORMAL_G = 204f / 255f;
+    private static final float NORMAL_B = 64f / 255f;
 
-    // Slot layout constants (in block units, 0-1 range)
-    private static final float SLOT_SIZE = 1.0f / 16.0f;  // 1 pixel
-    private static final float SLOT_SPACING = 2.0f / 16.0f;  // 2 pixels between slots
+    // Error state: Red
+    private static final float ERROR_R = 204f / 255f;
+    private static final float ERROR_G = 64f / 255f;
+    private static final float ERROR_B = 64f / 255f;
 
-    // Starting position for the slot grid
-    private static final float GRID_START_X = 3.0f / 16.0f;
-    private static final float ROW1_Y = 9.0f / 16.0f;
-    private static final float ROW2_Y = 12.0f / 16.0f;
+    // Warning state: Yellow
+    private static final float WARNING_R = 204f / 255f;
+    private static final float WARNING_G = 204f / 255f;
+    private static final float WARNING_B = 64f / 255f;
+
+    // Disk edge color (matching disk texture - dark red/burgundy)
+    private static final float DISK_R = 139f / 255f;
+    private static final float DISK_G = 35f / 255f;
+    private static final float DISK_B = 35f / 255f;
+
+    // Pulse parameters for each status
+    private static final float NORMAL_PULSE_SPEED = 0.1f;
+    private static final float NORMAL_PULSE_AMPLITUDE = 0.15f;
+    private static final float WARNING_PULSE_SPEED = 0.2f;
+    private static final float WARNING_PULSE_AMPLITUDE = 0.25f;
+    private static final float ERROR_PULSE_SPEED = 0.4f;
+    private static final float ERROR_PULSE_AMPLITUDE = 0.35f;
+
+    // Base brightness for indicators
+    private static final float BASE_BRIGHTNESS = 0.7f;
+
+    // Layout constants based on 128x128 texture
+    // Texture generator uses: GRID_START_X=4, ROW1_Y=48, ROW2_Y=72, COL_SPACING=25
+    // SLOT_WIDTH=16, SLOT_HEIGHT=6, LIGHT_SIZE=4
+    private static final float TEX = 128.0f;
+
+    // Disk slot dimensions
+    private static final float SLOT_WIDTH = 16.0f / TEX;
+    private static final float SLOT_HEIGHT = 6.0f / TEX;
+    private static final float COL_SPACING = 25.0f / TEX;
+    private static final float GRID_START_X = 4.0f / TEX;
+    private static final float ROW1_Y = 48.0f / TEX;
+    private static final float ROW2_Y = 72.0f / TEX;
+
+    // Indicator light position (right side of slot)
+    private static final float LIGHT_OFFSET_X = SLOT_WIDTH + 2.5f / TEX;
+    private static final float LIGHT_SIZE = 3.0f / TEX;
+    private static final float LIGHT_OFFSET_Y = (SLOT_HEIGHT - LIGHT_SIZE) / 2.0f;
+
+    // Disk line dimensions (thin red line inside slot)
+    private static final float DISK_LINE_INSET = 1.0f / TEX;
+    private static final float DISK_LINE_HEIGHT = 2.0f / TEX;
 
     // Z offset to prevent z-fighting
     private static final float Z_OFFSET = -0.001f;
+    private static final float Z_GLOW_OFFSET = -0.002f;
+
+    // Glow effect
+    private static final float GLOW_SIZE_MULTIPLIER = 1.5f;
+    private static final float GLOW_ALPHA = 0.5f;
 
     public LibraryBlockEntityRenderer(BlockEntityRendererProvider.Context context) {
     }
@@ -50,8 +97,15 @@ public void render(
         int diskMask = blockEntity.getDiskSlotMask();
         if (diskMask == 0) return;
 
+        int errorMask = blockEntity.getErrorSlotMask();
+        int warningMask = blockEntity.getWarningSlotMask();
+
         Direction facing = blockEntity.getBlockState().getValue(LibraryBlock.FACING);
 
+        // Calculate time for pulsing animation
+        Level level = blockEntity.getLevel();
+        float gameTime = level != null ? level.getGameTime() + partialTick : 0;
+
         poseStack.pushPose();
 
         // Move to center of block
@@ -72,46 +126,179 @@ public void render(
         // Move back from center
         poseStack.translate(-0.5, -0.5, -0.5);
 
-        // Set up rendering for colored quads
+        Matrix4f matrix = poseStack.last().pose();
+
+        // Set up rendering for colored quads with blending for glow
         RenderSystem.enableDepthTest();
+        RenderSystem.enableBlend();
+        RenderSystem.defaultBlendFunc();
         RenderSystem.setShader(GameRenderer::getPositionColorShader);
 
         Tesselator tesselator = Tesselator.getInstance();
         BufferBuilder buffer = tesselator.getBuilder();
 
-        Matrix4f matrix = poseStack.last().pose();
+        // First pass: render disk lines (thin red line in each occupied slot)
+        buffer.begin(VertexFormat.Mode.QUADS, DefaultVertexFormat.POSITION_COLOR);
 
+        for (int slot = 0; slot < LibraryBlockEntity.DISK_SLOT_COUNT; slot++) {
+            if ((diskMask & (1 << slot)) != 0) {
+                renderDiskLine(buffer, matrix, slot);
+            }
+        }
+
+        tesselator.end();
+
+        // Second pass: render glow effects (larger, semi-transparent)
         buffer.begin(VertexFormat.Mode.QUADS, DefaultVertexFormat.POSITION_COLOR);
 
-        // Render indicators for each occupied slot
         for (int slot = 0; slot < LibraryBlockEntity.DISK_SLOT_COUNT; slot++) {
             if ((diskMask & (1 << slot)) != 0) {
-                renderSlotIndicator(buffer, matrix, slot);
+                int slotBit = 1 << slot;
+                float r, g, b, pulseSpeed, pulseAmplitude;
+
+                // Priority: error (red) > warning (yellow) > normal (green)
+                if ((errorMask & slotBit) != 0) {
+                    r = ERROR_R;
+                    g = ERROR_G;
+                    b = ERROR_B;
+                    pulseSpeed = ERROR_PULSE_SPEED;
+                    pulseAmplitude = ERROR_PULSE_AMPLITUDE;
+                } else if ((warningMask & slotBit) != 0) {
+                    r = WARNING_R;
+                    g = WARNING_G;
+                    b = WARNING_B;
+                    pulseSpeed = WARNING_PULSE_SPEED;
+                    pulseAmplitude = WARNING_PULSE_AMPLITUDE;
+                } else {
+                    r = NORMAL_R;
+                    g = NORMAL_G;
+                    b = NORMAL_B;
+                    pulseSpeed = NORMAL_PULSE_SPEED;
+                    pulseAmplitude = NORMAL_PULSE_AMPLITUDE;
+                }
+
+                // Calculate pulse with slot-based phase offset for visual variety
+                float phaseOffset = slot * 0.5f;
+                float pulse = (float) (Math.sin((gameTime + phaseOffset) * pulseSpeed) * 0.5 + 0.5);
+                float intensity = BASE_BRIGHTNESS + pulse * pulseAmplitude;
+
+                // Render glow (larger, semi-transparent)
+                renderGlow(buffer, matrix, slot, r * intensity, g * intensity, b * intensity);
             }
         }
 
         tesselator.end();
 
+        // Third pass: render main indicator lights
+        buffer.begin(VertexFormat.Mode.QUADS, DefaultVertexFormat.POSITION_COLOR);
+
+        for (int slot = 0; slot < LibraryBlockEntity.DISK_SLOT_COUNT; slot++) {
+            if ((diskMask & (1 << slot)) != 0) {
+                int slotBit = 1 << slot;
+                float r, g, b, pulseSpeed, pulseAmplitude;
+
+                if ((errorMask & slotBit) != 0) {
+                    r = ERROR_R;
+                    g = ERROR_G;
+                    b = ERROR_B;
+                    pulseSpeed = ERROR_PULSE_SPEED;
+                    pulseAmplitude = ERROR_PULSE_AMPLITUDE;
+                } else if ((warningMask & slotBit) != 0) {
+                    r = WARNING_R;
+                    g = WARNING_G;
+                    b = WARNING_B;
+                    pulseSpeed = WARNING_PULSE_SPEED;
+                    pulseAmplitude = WARNING_PULSE_AMPLITUDE;
+                } else {
+                    r = NORMAL_R;
+                    g = NORMAL_G;
+                    b = NORMAL_B;
+                    pulseSpeed = NORMAL_PULSE_SPEED;
+                    pulseAmplitude = NORMAL_PULSE_AMPLITUDE;
+                }
+
+                float phaseOffset = slot * 0.5f;
+                float pulse = (float) (Math.sin((gameTime + phaseOffset) * pulseSpeed) * 0.5 + 0.5);
+                float intensity = BASE_BRIGHTNESS + pulse * pulseAmplitude;
+
+                renderSlotIndicator(buffer, matrix, slot, r * intensity, g * intensity, b * intensity);
+            }
+        }
+
+        tesselator.end();
+
+        RenderSystem.disableBlend();
         poseStack.popPose();
     }
 
-    private void renderSlotIndicator(BufferBuilder buffer, Matrix4f matrix, int slot) {
+    private void renderDiskLine(BufferBuilder buffer, Matrix4f matrix, int slot) {
+        int row = slot / 5;
+        int col = 4 - (slot % 5);  // Mirror column to match GUI layout
+
+        float slotX = GRID_START_X + col * COL_SPACING;
+        float slotY = (row == 0) ? ROW1_Y : ROW2_Y;
+
+        // Thin red line inside the slot (representing disk edge)
+        // Mirror X coordinate (1.0f - x) to match texture orientation on north face
+        float x1 = 1.0f - slotX - SLOT_WIDTH + DISK_LINE_INSET;
+        float x2 = 1.0f - slotX - DISK_LINE_INSET;
+        float y1 = 1.0f - slotY - SLOT_HEIGHT / 2.0f - DISK_LINE_HEIGHT / 2.0f;
+        float y2 = 1.0f - slotY - SLOT_HEIGHT / 2.0f + DISK_LINE_HEIGHT / 2.0f;
+        float z = Z_OFFSET;
+
+        buffer.vertex(matrix, x1, y1, z).color(DISK_R, DISK_G, DISK_B, 1.0f).endVertex();
+        buffer.vertex(matrix, x1, y2, z).color(DISK_R, DISK_G, DISK_B, 1.0f).endVertex();
+        buffer.vertex(matrix, x2, y2, z).color(DISK_R, DISK_G, DISK_B, 1.0f).endVertex();
+        buffer.vertex(matrix, x2, y1, z).color(DISK_R, DISK_G, DISK_B, 1.0f).endVertex();
+    }
+
+    private void renderSlotIndicator(BufferBuilder buffer, Matrix4f matrix, int slot, float r, float g, float b) {
         int row = slot / 5;
         int col = 4 - (slot % 5);  // Mirror column to match GUI layout
 
-        float x = GRID_START_X + col * SLOT_SPACING;
-        float y = (row == 0) ? ROW1_Y : ROW2_Y;
+        float slotX = GRID_START_X + col * COL_SPACING;
+        float slotY = (row == 0) ? ROW1_Y : ROW2_Y;
 
-        float x1 = x;
-        float x2 = x + SLOT_SIZE;
-        float y1 = 1.0f - y - SLOT_SIZE;
-        float y2 = 1.0f - y;
+        // Light position is to the right of the disk slot in texture space
+        // Mirror X coordinate (1.0f - x) to match texture orientation on north face
+        float x1 = 1.0f - slotX - LIGHT_OFFSET_X - LIGHT_SIZE;
+        float x2 = 1.0f - slotX - LIGHT_OFFSET_X;
+        float y1 = 1.0f - slotY - LIGHT_OFFSET_Y - LIGHT_SIZE;
+        float y2 = 1.0f - slotY - LIGHT_OFFSET_Y;
         float z = Z_OFFSET;
 
         // Quad on the north face (z=0)
-        buffer.vertex(matrix, x1, y1, z).color(AMBER_R, AMBER_G, AMBER_B, 1.0f).endVertex();
-        buffer.vertex(matrix, x1, y2, z).color(AMBER_R, AMBER_G, AMBER_B, 1.0f).endVertex();
-        buffer.vertex(matrix, x2, y2, z).color(AMBER_R, AMBER_G, AMBER_B, 1.0f).endVertex();
-        buffer.vertex(matrix, x2, y1, z).color(AMBER_R, AMBER_G, AMBER_B, 1.0f).endVertex();
+        buffer.vertex(matrix, x1, y1, z).color(r, g, b, 1.0f).endVertex();
+        buffer.vertex(matrix, x1, y2, z).color(r, g, b, 1.0f).endVertex();
+        buffer.vertex(matrix, x2, y2, z).color(r, g, b, 1.0f).endVertex();
+        buffer.vertex(matrix, x2, y1, z).color(r, g, b, 1.0f).endVertex();
+    }
+
+    private void renderGlow(BufferBuilder buffer, Matrix4f matrix, int slot, float r, float g, float b) {
+        int row = slot / 5;
+        int col = 4 - (slot % 5);  // Mirror column to match GUI layout
+
+        float slotX = GRID_START_X + col * COL_SPACING;
+        float slotY = (row == 0) ? ROW1_Y : ROW2_Y;
+
+        // Glow centered on the light position
+        // Mirror X coordinate (1.0f - x) to match texture orientation on north face
+        float lightX = 1.0f - slotX - LIGHT_OFFSET_X - LIGHT_SIZE / 2.0f;
+        float lightY = slotY + LIGHT_OFFSET_Y + LIGHT_SIZE / 2.0f;
+
+        float glowSize = LIGHT_SIZE * GLOW_SIZE_MULTIPLIER;
+        float halfGlow = glowSize / 2.0f;
+
+        float x1 = lightX - halfGlow;
+        float x2 = lightX + halfGlow;
+        float y1 = 1.0f - lightY - halfGlow;
+        float y2 = 1.0f - lightY + halfGlow;
+        float z = Z_GLOW_OFFSET;
+
+        // Semi-transparent glow quad
+        buffer.vertex(matrix, x1, y1, z).color(r, g, b, GLOW_ALPHA).endVertex();
+        buffer.vertex(matrix, x1, y2, z).color(r, g, b, GLOW_ALPHA).endVertex();
+        buffer.vertex(matrix, x2, y2, z).color(r, g, b, GLOW_ALPHA).endVertex();
+        buffer.vertex(matrix, x2, y1, z).color(r, g, b, GLOW_ALPHA).endVertex();
     }
 }
diff --git a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
index b704b6c27..ecc0a937c 100644
--- a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
+++ b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
@@ -292,6 +292,8 @@ public void clearContent() {
 
     // Client-side cache of disk mask for rendering
     private int clientDiskMask = 0;
+    private int clientErrorMask = 0;
+    private int clientWarningMask = 0;
 
     @Override
     public void setChanged() {
@@ -338,6 +340,8 @@ public void recompileAllDisks() {
     public CompoundTag getUpdateTag() {
         CompoundTag tag = super.getUpdateTag();
         tag.putInt("DiskMask", computeDiskMask());
+        tag.putInt("ErrorMask", computeErrorMask());
+        tag.putInt("WarningMask", computeWarningMask());
         return tag;
     }
 
@@ -345,6 +349,8 @@ public CompoundTag getUpdateTag() {
     public void handleUpdateTag(CompoundTag tag) {
         super.handleUpdateTag(tag);
         clientDiskMask = tag.getInt("DiskMask");
+        clientErrorMask = tag.getInt("ErrorMask");
+        clientWarningMask = tag.getInt("WarningMask");
     }
 
     @Override
@@ -357,6 +363,8 @@ public void onDataPacket(net.minecraft.network.Connection net, ClientboundBlockE
         CompoundTag tag = pkt.getTag();
         if (tag != null) {
             clientDiskMask = tag.getInt("DiskMask");
+            clientErrorMask = tag.getInt("ErrorMask");
+            clientWarningMask = tag.getInt("WarningMask");
         }
     }
 
@@ -373,6 +381,34 @@ private int computeDiskMask() {
         return mask;
     }
 
+    /**
+     * Computes a bitmask indicating which slots have disks with errors (server-side).
+     */
+    private int computeErrorMask() {
+        int mask = 0;
+        for (int i = 0; i < items.size(); i++) {
+            ItemStack disk = items.get(i);
+            if (DiskItem.isValidDisk(disk) && !DiskItem.getErrors(disk).isEmpty()) {
+                mask |= (1 << i);
+            }
+        }
+        return mask;
+    }
+
+    /**
+     * Computes a bitmask indicating which slots have disks with warnings (server-side).
+     */
+    private int computeWarningMask() {
+        int mask = 0;
+        for (int i = 0; i < items.size(); i++) {
+            ItemStack disk = items.get(i);
+            if (DiskItem.isValidDisk(disk) && !DiskItem.getWarnings(disk).isEmpty()) {
+                mask |= (1 << i);
+            }
+        }
+        return mask;
+    }
+
     /**
      * Returns a bitmask indicating which slots have disks.
      * Bit 0 = slot 0, bit 1 = slot 1, etc.
@@ -384,4 +420,28 @@ public int getDiskSlotMask() {
         }
         return computeDiskMask();
     }
+
+    /**
+     * Returns a bitmask indicating which slots have disks with errors.
+     * Bit 0 = slot 0, bit 1 = slot 1, etc.
+     * Used by the BlockEntityRenderer to show error indicators.
+     */
+    public int getErrorSlotMask() {
+        if (level != null && level.isClientSide()) {
+            return clientErrorMask;
+        }
+        return computeErrorMask();
+    }
+
+    /**
+     * Returns a bitmask indicating which slots have disks with warnings.
+     * Bit 0 = slot 0, bit 1 = slot 1, etc.
+     * Used by the BlockEntityRenderer to show warning indicators.
+     */
+    public int getWarningSlotMask() {
+        if (level != null && level.isClientSide()) {
+            return clientWarningMask;
+        }
+        return computeWarningMask();
+    }
 }
diff --git a/src/main/resources/assets/sfm/textures/block/library_back.png b/src/main/resources/assets/sfm/textures/block/library_back.png
index 9d6cb864c55911d9bed961f9f58bd9d934b48658..60700e05f0fd8f2531242e9ccef4ae4dc165424e 100644
GIT binary patch
literal 791
zcmeAS@N?(olHy`uVBq!ia0vp^4Is?H1|$#LC7xzrV7lk&;uum9_x8@&%;Z1;mqd1j
z3vrejEUF9seBM~e?Hst}z=Jyb?XPwA^*%Ssoqp~V^XIQsd-wf+RJT7_@!!wdPfz22
zr2O{2|K40|Lo~zr=fd0y4FxO$eGG>L9W0nQ+!-EnD9A9jC^r<evu&uAeSV|v?d$o+
zH5qN>_~$fWDq<1H>txtwfB&?Z!!6sbJ`CG$=Zar-xcpv|NrP=xoxh-i;e{{NT?}1~
z%kBrW1n`*rou|~0wBY4;5k?Va-~G!u7D#0LvUO!RIs~-n3Lg08`%d%iy!+qIKQ3ZS
zu*Vu|2*L7BhPwY(xt@PG|M&w#fh|G;7RJ^l4R2pt99OLq+){hD-nBDX04)ZTnQ#2t
zck<8kzx^8-f7DMgaQz;}vSG%%wHyhCccTRlB<<R+)Nr&UUsST8KK|VO^3T=h?ym;Q
zE_m>M_fOmB??Zvg13rAe`)A(g@2je{nKXX<&Z|5Bv-;{@QAUwJwdVVu|JnQMUKaz`
zzkRds7ypYZ&39#Bt-pWvy=DD+kkL*1-#`04XMgzJXjirkn=q_(W$1o+FDr*(^3U_X
z<&~Ka+(%D9(>W4;s};!ox8dVwxbBQdSSTS;#?A2h!}<5ZOcJN;_xsl|<nLeOY2-8G
RJ21gBc)I$ztaD0e0s!v_O-29!

literal 119
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`cAhSdAr*1S8@3w#_Sc&>N#OT+
zhNKr+D<`%F@-P&798^BY5GSW6(xYcD#G}yCzL@bz!UjeI;fv051=?ORGdOIIwA9>h
Rzz;Nu!PC{xWt~$(698$MBL@Hg

diff --git a/src/main/resources/assets/sfm/textures/block/library_bot.png b/src/main/resources/assets/sfm/textures/block/library_bot.png
index 5893c3c2d147485a5bd47e14529f35ba4e566eba..3e04930b744e5c1ca10fe710d25093428cd6d285 100644
GIT binary patch
literal 1019
zcmeAS@N?(olHy`uVBq!ia0vp^4Is?H1|$#LC7xzrU_RvO;uum9_jZn9(H#Q;maomH
zzcQp&HQ6or|Nr<p?ts*_uUYuo6~wyvZk;@#leL@Kt*Y8au0A3D-n{=c_4S9-{)iv=
z{o6W+g)xT@37vb$aEpJQsvW<{BiqnNpC1+TvwrycwY2Mg97CVstA8vTI2OOF*J{|Y
z_t6RN1BPyQ|8HYBaC~R|9jUiB4>SMx^M{4``@h0$fdfiAzV}BrGl(7B3zP%udiVG7
zHH8M(g7@;<*%)=2s{ijW<wy{`^ZWQ(M~3bP_w4g}gBe!{H1t>he=(Us?C{?DFO^yh
z?LW91-S#Z^`XafvjJd<6-fo}D6Nj%J3`YZOg&Yh+`dI>au0Ec^U}tAnci>-fIY{)-
zT}Pk-&T{sv%8V*^WJCIcnHmaL$Z;-^Smn;7(e`R0L)XHpIYJKal{3DhD`lBb05rpo
zli}FHDwT#LBwdAG414<*+(noQQ3|onLX|<H9bzzC*Ktk8FLq63_kj*TRtj+$(8)2k
zy3<wny`Q^6ZoZDB!=GS{$QiZLKqtqXd2<_R?}MbY`)*$?R2%NO2jriZb9n!^dUrF>
z3cWT4z6;h4`RWbV!KyeOux(-&xc}V`Xib6P=KRG#cX!W3GHE%>h2I>n-ri(>v9~@S
z6hH@#3LIdpVt?_L<%87K$D0^amVN)X7Z?yfo_u3SkU<I~uvfs^Z`BT_kVV8IBCwqq
zx5(Rg*LYs&_#V<}xA?j<;}QGTqAAb+_wE<S0478`&IH3dzuo7DF%(uG-LEfDuXq7>
zLgZzNV8NY+cjz`e-~7-9l$?Rg9gW9U{GQL{@N~O)Lvqh9dq$l@D}H-3S{!)}PPa92
uHF@R?D>#wz7cj4#>t{%a=SV32$7CbF<ykw6ybLf?GkCiCxvX<aXaWGr!nZ{L

literal 158
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`sh%#5Ar)~;&l++y7znsrys~I*
z2m1zr99@?8^=mxd2>oBMS<HU&tK3=34c)E#ZI^$#c}+Ehb<3}44xZZYm4XFM4SFkG
z4{$Q>S|Y}%&hlbX6w4fe1>RW@iCTt<c?)dncQO398F71F-IK>a3mH6J{an^LB{Ts5
DrhYjS

diff --git a/src/main/resources/assets/sfm/textures/block/library_front.png b/src/main/resources/assets/sfm/textures/block/library_front.png
index b2fa63c0b060eb5d0d40587db2eb07fd990ef536..cfa498f6c9441f6077b5ff232bf92570ed49a161 100644
GIT binary patch
literal 930
zcmeAS@N?(olHy`uVBq!ia0vp^4Is?H1|$#LC7xzrV9xY(aSW-5dwc6*rnaGg+e49r
z4fD6NPk+F6r{4biBKAhx)i)=mN^bc)zg?eY?Sx5lnK@PJufP5(U-EY<|M};_No9<8
z-j{PIG8D2X^f4R}Y_MPwxGw8(x8w86nc3kCx3@iPS+rBgq3B`^r^3#Rbu1HNOv0Hw
z^k%)D!jQN9w&J(<-_P8sSDB^FsB!~H0Yx{gLsA747C&3+#qe#qNcZ30w#MJ(JD+(m
zaDD?)R;mnZv_bmB&rW5S)D09q=~_HjsNt{b(WL)%=g<6g2ie;MqWm}+UUxwhs5U&o
z>Kvd`pGuxPeeUyPh6%!q9m>ewac6kM;UL4<ahvr+h0U@};$mgzx4-#$=i%n(=FA&r
zyH%!FzE<9|dCynDdy)5kalF^buXTB?W8Uy9!R2pY((CG@vajz1elua-5u@iEr@!U=
z8}rop-yikWU6f^c5U{hEK}M@wpuzcRUmC;H&-qulZSQP6CwrD5?ZdfG*W4>m%<i}r
znfh)wL)s?sYx*f_)pq4S-u&Fn@P_S)8`OnZoedVu6L0wY`Qi3At*v)I>q2y%Wq7kJ
z5borb@@d=c4q2a$mcM9qns<SnL}2}t8^7WTk6V>bu>~r%7x-4S_k!K#`%`M~bzA>(
z1-qG#sbIw&M+UyB*0UI=oZla)|D^z^-h_F^L6AWY=RRHAkMKrR`qZ88nP!}fi`YM5
zCM5jcGi{KbAdMrqaeHQ+b;B;f=a-GIuVZ*qKjV=M));;5&$NQQ`c2)Q&F@cd`rYqR
ztXn5^U|X*5{CP_=p8W=;7w%a<{{gigXiD3+ADHGgESULTADEzYP^ACqG$@zZ-@Exe
x^(H7OiCtzsV1?B_oGEC>c7_Gr3`hR5uf2caf!8$eFTlLV;OXk;vd$@?2>^h~p{4);

literal 140
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`!JaOTAr*1S8@3w#_Sc&>N#OT+
zhNKr+D<`%F@-P&79E{+7@bsY)7k?77$3Y3U3C$~CGYPOivv)Fi%cH=WY|3y~Eyg65
nM}fVWw_zrS(OeOp%j^t+_rp%dtBFYfjc4$5^>bP0l+XkK<FqOb

diff --git a/src/main/resources/assets/sfm/textures/block/library_side.png b/src/main/resources/assets/sfm/textures/block/library_side.png
index bb87c528a8ce8481a0c8dac1ed04bdca8ec6ba90..524c93ebb89ad6d7d4edf994fdad7164b9642050 100644
GIT binary patch
literal 916
zcmeAS@N?(olHy`uVBq!ia0vp^4Is?H1|$#LC7xzrV2<{5aSW-5dwbonODRyq<>IZz
zzPruN?Rf|OzF$5oN5kW=#-@3n&VKK;wh-ai_TiCJdR^@L>+knl$nf3Ye*5kJ_%GXY
zmP%X2|2mjo_b>2^xk<z4pFPhw6l54%lp6|I1o{{b2|8FXakw))<WRU1%^YEO-0qIt
zZk7V8xf__bvoo?3Rtq=?Y(IXP@x_0AdyWPA+uPX|RKHqR&iH~~z#%`6U%a8NpTVx>
z_TpHE>8DxsFI2DFX?u&cz((#P)86N^Za-eiAj5QH`n}?_Zyz!h$T8h;V)%WbI*j>-
zkqtx7<8KNL3VHlY9FM?^{xZfF)w)?<=3Qo8;J<an#cCl3iM{HKEf=f(#2Jo390GTd
z`)-CWd&Nwv&c9^3usrI@3tLWwo_muS4!y8l&du<6hb@Of$L(f@CI|!QxL<MIQhT45
zFun)|*}x*;_TG~r5oA?E;T<`D_6;>B6&v>5k&|k8w{rJA)&=$s410Il#xVS{W%?nI
z2X|REm<cul$ehkpz>yGNb>4J)JNJP~js$MTH_q=Pc@s{5U@+)I*ba8aE!G9^L4NWR
zZ?L<%2x>dX8J4jO635><GC1CmV-Yw4VZ3F!@Ezo*<=hVQvjP`?S7|V)@@L{${C$od
z$)RQ=d*G95JHxM{>I{Zm%imRrH~eE@{POHu0ppAB91om#0AmZ{GH}E}0v^bW<2s<&
zQ2WyM`W-nvhUbb6x-1*`_okaR=pJT1V1bA;aO7o(H|)C(^b^o4ze0e)430BU<N?Dw
zK?aeEz>&9w+u?pT&`&_G)UI;vg~S;s@``s+7;5?a2|sy$U$ng^$M8!LBXL7gyfbse
izeV;;9N(`q{9}yxAoF?osWwplWAJqKb6Mw<&;$TC1BI6W

literal 148
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`(Vi}jAr*1S8@3w#_Sc&>N#OT+
zhNKr+D<`%F@-P&79Nc2uFuk2yUoC@Sqr`H?7iNo+o7e=p3#A(Jl&#PN*%vZCN!Y+>
iAbgRzTcGVFGsCygu$Lm7(cD057(8A5T-G@yGywpEDK2jS

diff --git a/src/main/resources/assets/sfm/textures/block/library_top.png b/src/main/resources/assets/sfm/textures/block/library_top.png
index e1afbeb72b267ee1829ebe73ef7bcdd031d8b0a7..626fd46fb42ce413f3ea9d02a0973ee9856d4f64 100644
GIT binary patch
literal 990
zcmeAS@N?(olHy`uVBq!ia0vp^4Is?H1|$#LC7xzrU|#C!;uum9_jcMvUl~UM*13!|
zlbID`n4Zk<U%PpWP+rvy%{3SOzF%`!Ecw0T_lipw_s7M>)t#>W`Ss7oj~^AyAA2*r
zfB(KnndiYX9_Eh!%67>bzlG=a{*hh3l+i}6UxfL_{K)!X#yxxY{#C7JzBxIvemSE|
z{hyz{JPGw_e<dA))Bet7EBGd=RBiM+U#p>m@y+=)`x6<?-`}rXx8RNI7g5Wy!wlyv
z{snw{tS(nC;$UNt!oR|uIfLzM2E*9}a=Z&9uPkOXX|6J9NDJs^yTJ3R(34^P`t_Rc
z_T~LcpYCWY<?t{Tq_(vjq)_BuDo|BG1zci>3d2smR~H#(fm9kp4BnyAP_d_{Z^n;1
zvbWKcV=+gM(_tNw^<bm)I2Gjd7b~mTl^-v|YAuR6-b@o-qx;00spI(R7ag7F?{38B
ze26)ZCow#+LJJh2*rSg|R!NVF%X8qqMX`1?7>G&@IFi{%cSf7-oAfVU??_}g-puof
zv55EL%@g-OMoArb{L#a(;qT0^=As8a?uRG(Bh1SC8sD5;W6zv%YR&%34CnSarTC})
z^<@=+DCT+a^LP0X{waGq_9-3DlW4fZ%)G<$Ka0ZmqYQcH<j<#;csp{vo(asi44$rj
JF6*2UngEc2qh0_2

literal 160
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!61|;P_|4#%`>7Fi*Ar*1S8@3w#_Sc&>N#OT+
zhNKr+D<`%F@?>}fFeFb<(B~JINKQU{CGb9jK)Xm!BEv4<mK#^h8SZwr7_>3&$T@U$
z**?Y>ekv`7JO@&R^~~BBMbuSNm_H=WVVlr=kZr+j2Q4;+iwy~vKC$t01FdB6boFyt
I=akR{08Z95C;$Ke


From 2ad77028b3d5f01ab4580b52794d57a1f46d204c Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 15:48:35 +0100
Subject: [PATCH 24/33] feat: redesign library GUI to match server rack
 aesthetic

---
 .../render/LibraryBlockEntityRenderer.java    |   6 +-
 .../sfm/client/screen/LibraryScreen.java      | 150 ++++++++----------
 .../sfm/textures/gui/container/library.png    | Bin 1728 -> 1821 bytes
 3 files changed, 69 insertions(+), 87 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java b/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java
index 472c0f0a8..8a09305a8 100644
--- a/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java
+++ b/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java
@@ -233,7 +233,7 @@ public void render(
 
     private void renderDiskLine(BufferBuilder buffer, Matrix4f matrix, int slot) {
         int row = slot / 5;
-        int col = 4 - (slot % 5);  // Mirror column to match GUI layout
+        int col = slot % 5;
 
         float slotX = GRID_START_X + col * COL_SPACING;
         float slotY = (row == 0) ? ROW1_Y : ROW2_Y;
@@ -254,7 +254,7 @@ private void renderDiskLine(BufferBuilder buffer, Matrix4f matrix, int slot) {
 
     private void renderSlotIndicator(BufferBuilder buffer, Matrix4f matrix, int slot, float r, float g, float b) {
         int row = slot / 5;
-        int col = 4 - (slot % 5);  // Mirror column to match GUI layout
+        int col = slot % 5;
 
         float slotX = GRID_START_X + col * COL_SPACING;
         float slotY = (row == 0) ? ROW1_Y : ROW2_Y;
@@ -276,7 +276,7 @@ private void renderSlotIndicator(BufferBuilder buffer, Matrix4f matrix, int slot
 
     private void renderGlow(BufferBuilder buffer, Matrix4f matrix, int slot, float r, float g, float b) {
         int row = slot / 5;
-        int col = 4 - (slot % 5);  // Mirror column to match GUI layout
+        int col = slot % 5;
 
         float slotX = GRID_START_X + col * COL_SPACING;
         float slotY = (row == 0) ? ROW1_Y : ROW2_Y;
diff --git a/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java b/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
index fdf2716e3..a1e5548b3 100644
--- a/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
+++ b/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
@@ -30,29 +30,25 @@ public class LibraryScreen extends AbstractContainerScreen<LibraryContainerMenu>
     private static final int PANEL_WIDTH = 120;
     private static final int PANEL_GAP = 4;
 
-    // Bezel/Frame colors (warm dark grays like old monitor plastic)
-    private static final int BEZEL_OUTER = 0xFF2D2A26;
-    private static final int BEZEL_INNER = 0xFF1A1816;
-    private static final int BEZEL_HIGHLIGHT = 0xFF3D3A36;
-
-    // Screen colors
-    private static final int SCREEN_BG = 0xFF0D0C0A;
-    private static final int SCREEN_EDGE = 0xFF050504;
-
-    // Amber phosphor text colors
-    private static final int TEXT_HEADER = 0xFFFFB84D;
-    private static final int TEXT_NORMAL = 0xFFCC9640;
-    private static final int TEXT_HOVER = 0xFFFFD080;
-    private static final int TEXT_DIM = 0xFF806020;
-
-    // Error/Warning colors (red phosphor style)
-    private static final int TEXT_ERROR = 0xFFFF4040;
-    private static final int TEXT_ERROR_DIM = 0xFFCC3030;
-    private static final int ERROR_GLOW = 0x40FF2020;
-    private static final int TEXT_WARNING = 0xFFFFCC40;
+    // Industrial server rack color palette (matching block textures)
+    private static final int PANEL_BG = 0xFF1A1A1A;        // Darkest background
+    private static final int PANEL_FRAME = 0xFF2D2D2D;    // Mid panel
+    private static final int PANEL_HIGHLIGHT = 0xFF4A4A4A; // Edge highlights
+    private static final int PANEL_SHADOW = 0xFF0F0F0F;   // Deep shadows
+    private static final int PANEL_LIGHT = 0xFF3D3D3D;    // Light metal accents
+
+    // Text colors (cool industrial)
+    private static final int TEXT_HEADER = 0xFF60C0C0;    // Cyan accent
+    private static final int TEXT_PRIMARY = 0xFFE0E0E0;   // Light gray
+    private static final int TEXT_SECONDARY = 0xFF707070; // Dim gray
+    private static final int TEXT_HOVER = 0xFFFFFFFF;     // White on hover
+    private static final int TEXT_ERROR = 0xFFFF6060;     // Error text
+    private static final int TEXT_WARNING = 0xFFE0E040;   // Warning text
 
     // Effects
-    private static final int CURSOR_GLOW = 0x30FFB84D;
+    private static final int HOVER_BAR = 0x40FFFFFF;      // Subtle highlight bar
+    private static final int ERROR_BAR = 0x30FF4040;      // Error highlight
+    private static final int WARNING_BAR = 0x30FFFF40;    // Warning highlight
 
     private int hoveredLibraryEntry = -1;
 
@@ -124,22 +120,24 @@ public void render(
         int screenY = this.topPos + 5;
         int screenRight = panelX + PANEL_WIDTH - 5;
 
-        // Header area with subtle background
+        // Header area with recessed metal panel effect
         int headerY = screenY + 2;
-        fill(poseStack, screenX + 3, headerY - 1, screenRight - 3, headerY + font.lineHeight + 2, 0x20FFB84D);
+        fill(poseStack, screenX + 3, headerY - 2, screenRight - 3, headerY + font.lineHeight + 3, PANEL_SHADOW);
+        fill(poseStack, screenX + 4, headerY - 1, screenRight - 4, headerY + font.lineHeight + 2, PANEL_BG);
 
-        // Header text - centered
+        // Header text - centered with cyan accent
         String header = "LIBRARY INDEX";
         int headerWidth = font.width(header);
         int headerX = screenX + (PANEL_WIDTH - 10 - headerWidth) / 2;
         font.drawShadow(poseStack, header, headerX, headerY, TEXT_HEADER);
 
-        // Divider line
-        int dividerY = headerY + font.lineHeight + 4;
-        fill(poseStack, screenX + 8, dividerY, screenRight - 8, dividerY + 1, TEXT_DIM);
+        // Horizontal divider lines (ventilation slit style)
+        int dividerY = headerY + font.lineHeight + 6;
+        fill(poseStack, screenX + 6, dividerY, screenRight - 6, dividerY + 1, PANEL_SHADOW);
+        fill(poseStack, screenX + 6, dividerY + 2, screenRight - 6, dividerY + 3, PANEL_HIGHLIGHT);
 
         // Content area starts below divider
-        int contentY = dividerY + 6;
+        int contentY = dividerY + 8;
         int textX = screenX + 6;
 
         // Reset hover state
@@ -147,13 +145,13 @@ public void render(
 
         if (menu.libraryEntries.isEmpty()) {
             // Show hint when no libraries are available
-            font.drawShadow(poseStack, "No libraries found", textX, contentY, TEXT_DIM);
+            font.drawShadow(poseStack, "No libraries found", textX, contentY, TEXT_SECONDARY);
             contentY += font.lineHeight + 2;
-            font.drawShadow(poseStack, "Insert disks with", textX, contentY, TEXT_DIM);
+            font.drawShadow(poseStack, "Insert disks with", textX, contentY, TEXT_SECONDARY);
             contentY += font.lineHeight;
-            font.drawShadow(poseStack, "NAME statements", textX, contentY, TEXT_DIM);
+            font.drawShadow(poseStack, "NAME statements", textX, contentY, TEXT_SECONDARY);
         } else {
-            // Draw library entries with slot numbers right-aligned
+            // Draw library entries with cursor indicator
             for (int i = 0; i < menu.libraryEntries.size(); i++) {
                 LibraryEntry entry = menu.libraryEntries.get(i);
 
@@ -161,50 +159,39 @@ public void render(
                 boolean hovered = mx >= screenX + 3 && mx <= screenRight - 3
                         && my >= contentY - 1 && my <= contentY + font.lineHeight + 1;
 
-                // Determine colors based on error/warning status
-                int bgGlow;
+                // Determine text color based on status
                 int textColor;
-                int statusColor;
-                String statusIndicator = "";
+                int barColor;
 
                 if (entry.hasErrors()) {
-                    // Error state - red phosphor effect
-                    bgGlow = hovered ? ERROR_GLOW : 0x20FF2020;
-                    textColor = hovered ? TEXT_ERROR : TEXT_ERROR_DIM;
-                    statusColor = TEXT_ERROR;
-                    statusIndicator = "!";
+                    textColor = hovered ? TEXT_ERROR : TEXT_PRIMARY;
+                    barColor = ERROR_BAR;
                 } else if (entry.hasWarnings()) {
-                    // Warning state - yellow/amber
-                    bgGlow = hovered ? CURSOR_GLOW : 0x20FFCC40;
-                    textColor = hovered ? TEXT_WARNING : TEXT_NORMAL;
-                    statusColor = TEXT_WARNING;
-                    statusIndicator = "?";
+                    textColor = hovered ? TEXT_WARNING : TEXT_PRIMARY;
+                    barColor = WARNING_BAR;
                 } else {
-                    // Normal state
-                    bgGlow = CURSOR_GLOW;
-                    textColor = hovered ? TEXT_HOVER : TEXT_NORMAL;
-                    statusColor = TEXT_DIM;
-                    statusIndicator = "";
+                    textColor = hovered ? TEXT_HOVER : TEXT_PRIMARY;
+                    barColor = HOVER_BAR;
                 }
 
+                // Draw hover highlight bar or status bar
                 if (hovered) {
                     hoveredLibraryEntry = i;
-                    // Draw hover glow background
-                    fill(poseStack, screenX + 3, contentY - 1, screenRight - 3, contentY + font.lineHeight + 1, bgGlow);
+                    fill(poseStack, screenX + 3, contentY - 1, screenRight - 3, contentY + font.lineHeight + 1, barColor);
                 } else if (entry.hasErrors()) {
-                    // Always show subtle error background glow
-                    fill(poseStack, screenX + 3, contentY - 1, screenRight - 3, contentY + font.lineHeight + 1, bgGlow);
+                    fill(poseStack, screenX + 3, contentY - 1, screenRight - 3, contentY + font.lineHeight + 1, ERROR_BAR);
+                } else if (entry.hasWarnings()) {
+                    fill(poseStack, screenX + 3, contentY - 1, screenRight - 3, contentY + font.lineHeight + 1, WARNING_BAR);
                 }
 
                 // Cursor indicator and library name
                 String cursor = hovered ? "> " : "  ";
                 font.drawShadow(poseStack, cursor + entry.name(), textX, contentY, textColor);
 
-                // Status indicator (! for error, ? for warning) and slot number right-aligned
-                String slotText = statusIndicator + "[" + (entry.slotIndex()) + "]";
+                // Slot number right-aligned
+                String slotText = "[" + entry.slotIndex() + "]";
                 int slotWidth = font.width(slotText);
-                font.drawShadow(poseStack, slotText, screenRight - 6 - slotWidth, contentY,
-                        statusIndicator.isEmpty() ? TEXT_DIM : statusColor);
+                font.drawShadow(poseStack, slotText, screenRight - 6 - slotWidth, contentY, TEXT_SECONDARY);
 
                 contentY += font.lineHeight + 3;
 
@@ -220,9 +207,9 @@ protected void renderLabels(
             int mx,
             int my
     ) {
-        // Draw title centered in the container area
-        this.font.draw(poseStack, this.title, (float) this.titleLabelX, (float) this.titleLabelY, 4210752);
-        this.font.draw(poseStack, this.playerInventoryTitle, (float) this.inventoryLabelX, (float) this.inventoryLabelY, 4210752);
+        // Draw title and inventory label with light text for readability on dark background
+        this.font.draw(poseStack, this.title, (float) this.titleLabelX, (float) this.titleLabelY, TEXT_PRIMARY);
+        this.font.draw(poseStack, this.playerInventoryTitle, (float) this.inventoryLabelX, (float) this.inventoryLabelY, TEXT_PRIMARY);
     }
 
     @Override
@@ -232,40 +219,35 @@ protected void renderBg(
             int mx,
             int my
     ) {
-        // Render the computer panel with CRT monitor bezel effect
+        // Render the industrial metal panel frame
         int panelX = this.leftPos - PANEL_WIDTH - PANEL_GAP;
         int panelY = this.topPos;
         int panelRight = panelX + PANEL_WIDTH;
         int panelBottom = panelY + imageHeight;
 
-        // Outer bezel (3px frame)
-        fill(matrixStack, panelX, panelY, panelRight, panelBottom, BEZEL_OUTER);
+        // Main panel background
+        fill(matrixStack, panelX, panelY, panelRight, panelBottom, PANEL_FRAME);
 
-        // Bezel highlight (top and left edges, 1px)
-        fill(matrixStack, panelX, panelY, panelRight, panelY + 1, BEZEL_HIGHLIGHT);
-        fill(matrixStack, panelX, panelY, panelX + 1, panelBottom, BEZEL_HIGHLIGHT);
+        // Clean outer border - dark edge
+        fill(matrixStack, panelX, panelY, panelRight, panelY + 1, PANEL_SHADOW);
+        fill(matrixStack, panelX, panelY, panelX + 1, panelBottom, PANEL_SHADOW);
+        fill(matrixStack, panelX, panelBottom - 1, panelRight, panelBottom, PANEL_SHADOW);
+        fill(matrixStack, panelRight - 1, panelY, panelRight, panelBottom, PANEL_SHADOW);
 
-        // Inner bezel shadow (bottom and right, 1px)
-        fill(matrixStack, panelX, panelBottom - 1, panelRight, panelBottom, SCREEN_EDGE);
-        fill(matrixStack, panelRight - 1, panelY, panelRight, panelBottom, SCREEN_EDGE);
+        // Inner lighter border for depth
+        fill(matrixStack, panelX + 1, panelY + 1, panelRight - 1, panelY + 2, PANEL_LIGHT);
+        fill(matrixStack, panelX + 1, panelY + 1, panelX + 2, panelBottom - 1, PANEL_LIGHT);
+        fill(matrixStack, panelX + 1, panelBottom - 2, panelRight - 1, panelBottom - 1, PANEL_LIGHT);
+        fill(matrixStack, panelRight - 2, panelY + 1, panelRight - 1, panelBottom - 1, PANEL_LIGHT);
 
-        // Inner frame (2px inset)
+        // Inner recessed area
         int innerX = panelX + 3;
         int innerY = panelY + 3;
         int innerRight = panelRight - 3;
         int innerBottom = panelBottom - 3;
-        fill(matrixStack, innerX, innerY, innerRight, innerBottom, BEZEL_INNER);
-
-        // Screen area (the "CRT glass")
-        int screenX = innerX + 2;
-        int screenY = innerY + 2;
-        int screenRight = innerRight - 2;
-        int screenBottom = innerBottom - 2;
-        fill(matrixStack, screenX, screenY, screenRight, screenBottom, SCREEN_BG);
-
-        // Screen edge darkening (vignette effect - 1px darker border inside screen)
-        fill(matrixStack, screenX, screenY, screenRight, screenY + 1, SCREEN_EDGE);
-        fill(matrixStack, screenX, screenY, screenX + 1, screenBottom, SCREEN_EDGE);
+
+        // Main display area (dark background)
+        fill(matrixStack, innerX, innerY, innerRight, innerBottom, PANEL_BG);
 
         // Render the main container background
         RenderSystem.setShader(GameRenderer::getPositionTexShader);
diff --git a/src/main/resources/assets/sfm/textures/gui/container/library.png b/src/main/resources/assets/sfm/textures/gui/container/library.png
index e2440b09cda96920637a8a32963e85c44299bc9f..489cc8d60f29d5915c48ed45dc27c85ed7045337 100644
GIT binary patch
literal 1821
zcmeAS@N?(olHy`uVBq!ia0y~yU<5K5893O0R7}x|GzJE?C!Q{jAr*0N?*?YccnY{)
zjBGey|L>FB9+vzAzwe*t`5LHDRIugHDfLpVbFJMAh2@GuUq<Cc{+OSCf8Ss4d9Um%
z<gdH_`TAPCat_mmMr#K9`hP0@fedCJtr+a<{wU0kW4zJ9@WF&NL7C~mWs!zn4hH{V
z1~VlF8()eg<_I;se*EP4uixL_|G(Rw9>8E$6ni9?>BHaO<#h{~3>q#oZTP2o_2aMF
zd;H(4t`#2YW8itX@1r{FgQriQu8*+~y!Ls!RiZmXn*u|v`Wub|0xS#Ox5zR|G%<Xc
zyFr=3S)gH`a2ZPi2h)XekXA>AUw$_P8x%Pl?sHl*8L%+EuqIyf!z~Ok@~^A+$iMsg
zbzOWd(9(h^h98Ao2N+ly>Vp{AfV_3_|F2z-f3z-L7VMaJ(m?TR=Iigh`qjB<-u|nk
z+ew~-m$N?j6><OZ--7k)%m2OtdbH&-(}DhA1~vtTKa-gZ7#JVS7inMw1%2X^<Gb%c
zg58VZL^K7_8OpHE_|xXt`QD5-PLvA%7h(7$DcaB*!WdC+(DH}p`tu+Lvmn-n8aFB>
zA`j7q*F80C@&5xRFyuVh)v=NxX7~61#@pwWZV3j(snZ?tU0erFpFSPG(~jfy&*-fX
zQ4WWA>#d!#j2wy#wQsMem9Z$aFnrk>JR6uO1eh*d_sdNJYNdgqj~WcuZ&vTgfAFg+
z+<Gf0@i^IV9jIkKaXtiSAA^4Ym|tD<SM^TSwTpglfoYhdF#d%W!|U0``K7f2z+|4a
zybPFxTYxFLEKAs$Nx+HW*R7SlZ#Wz{7++*BH`}Pppvbad{oGqeXrt&+Aj7)N-z)AP
z04Dyjto^@$wp55T{AQale<jdS4D%L%`QLy1^4{@v&EmPYfN5Re(Y_0z!1SLEO#cdN
zp66eM_>0a#54Y~fVuqOX_aFB)zJ4A1_DbDXU=RbN<vXu}eK06J*f=tB1hPKZ_2S89
z4F<+l3=__;V90S{sF=mHVWJkpb;+MRzqB1XUMnqQ`ta+v#p_6S>#e||Md3*8!qp6G
z{yRKgyN>@*)xWT}S3o5UO%oH`M_AG>FjbX)lY1|{W8XbsaEIRqI;Eef;6B4AV^N@^
z4hV}h2mo_xx1U`%lfVKlhMzrL2i#a1mTNLdSIRPc5@Agcw%&Kuy{-*d54={Iw0xJ{
gd0;Iw2*8}P^@?jA?Oc83j}FK+p00i_>zopr07WO5;Q#;t

literal 1728
zcmeAS@N?(olHy`uVBq!ia0y~yU<5K5893O0R7}x|GzJE?c25__kczmscQ<w|4Ham;
z$T`QwMD!yg4@)rf!SD5JCi1a$*{`sUEoWcOmwj-0*oWd9m%p(5eY(H?|4+5tH~shP
ze}8NJUQ=^o|NmdXQPUYYe%LX{%Lm_@#K^Id`9n;^%OgAv6BsXSqa}G^8{>~(Uzcw$
zUjF{)S^v`vEV(ib@%2A{uD$cJy6*F3BL+vdgnMVp{mwD4NH$cO-?y}67D!=ucDLsF
z6OglJlz*N(*_cj>fNq_@;{bB;5Ak<*;SQ8$fACZJbvoP!1MW^lu-s;I0EM8#?IA&~
zXM6B?{n>r9t!v+XvAw^9k>l4y#)^MGUz~sDH{ZJUym=-=6VCyg@?Vq6v)B|)Fq|n~
zu3x!4ZSV-bxXR$MJe8p-j`zUvru}H%@c4G~&Pz}lQR4-r+vk4qpZv~(6ZN|<s_(CW
z6Z7B@+$+WKatkn>uV(xa@u9qU`T4o~p3gR6aI`mKI4^(F4&g5&hR=6idf!_q*`UB|
z095s4?kq-*!6LXIoLOP+G?064VI`|f8RYjLtu-(I1<c6%JedW)C^LWflRtB)B{rUh
zZNMalOul09h&EzSywC0c@_B{c>MbjuSA%K|nt+D8|JdUfE6#Arbu<TA;OXk;vd$@?
F2>`D(vd#bi


From 013f4990c84d969a091c3af94db09ff090d89964 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 17:20:04 +0100
Subject: [PATCH 25/33] fix: recompile libraries and managers on cable network
 changes

---
 .../blockentity/LibraryBlockEntity.java       | 16 ++++++-
 .../cablenetwork/CableNetworkManager.java     | 44 ++++++++++++++++++-
 2 files changed, 56 insertions(+), 4 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
index ecc0a937c..82e52138e 100644
--- a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
+++ b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
@@ -309,14 +309,23 @@ public void setChanged() {
     /**
      * Notifies any cable networks adjacent to this library block that the library
      * configuration has changed, causing managers and other library disks to recompile.
+     * If not connected to any network, recompiles local disks directly.
      */
     private void notifyNetworkLibraryChanged() {
         if (level == null || level.isClientSide()) return;
 
         // Find networks adjacent to this library block and notify them
-        CableNetworkManager.getNetworksForLevel(level)
+        boolean onNetwork = CableNetworkManager.getNetworksForLevel(level)
                 .filter(network -> network.isAdjacentToCable(worldPosition))
-                .forEach(CableNetwork::invalidateAutoLabelsAndNotifyDependents);
+                .peek(CableNetwork::invalidateAutoLabelsAndNotifyDependents)
+                .findAny()
+                .isPresent();
+
+        // If not on a network, recompile local disks to update errors
+        // (e.g., resolved circular dependencies)
+        if (!onNetwork) {
+            recompileAllDisks();
+        }
     }
 
     /**
@@ -333,6 +342,9 @@ public void recompileAllDisks() {
 
             DiskItem.compileAndUpdateErrorsAndWarnings(disk, null, true, resolver);
         }
+
+        // Sync to client for renderer updates (without triggering network notification)
+        level.sendBlockUpdated(worldPosition, getBlockState(), getBlockState(), 3);
     }
 
     // Client sync methods for BlockEntityRenderer
diff --git a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java
index f0cb3aaf2..acd27c8e7 100644
--- a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java
+++ b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java
@@ -1,6 +1,7 @@
 package ca.teamdman.sfm.common.cablenetwork;
 
 import ca.teamdman.sfm.SFM;
+import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
 import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
 import ca.teamdman.sfm.common.util.SFMDirections;
 import ca.teamdman.sfm.common.util.SFMStreamUtils;
@@ -96,19 +97,58 @@ public static void unregisterNetworkForTestingPurposes(CableNetwork network) {
 
     public static void onCablePlaced(Level level, BlockPos pos) {
         if (level.isClientSide()) return;
-        getOrRegisterNetworkFromCablePosition(level, pos);
+        getOrRegisterNetworkFromCablePosition(level, pos).ifPresent(network -> {
+            // Invalidate and rebuild auto labels to discover newly connected blocks
+            network.invalidateAutoLabelsAndNotifyDependents();
+        });
     }
 
     public static void onCableRemoved(Level level, BlockPos cablePos) {
         getNetworkFromCablePosition(level, cablePos).ifPresent(network -> {
+            // Capture library and manager positions before invalidating the network
+            Set<BlockPos> libraryPositions = network.getOrRebuildAutoLabels()
+                    .getPositions(LibraryBlockEntity.LIBRARY_LABEL);
+            Set<BlockPos> managerPositions = network.getOrRebuildAutoLabels()
+                    .getPositions(ManagerBlockEntity.MANAGER_LABEL);
+
             // Invalidate the original network
             removeNetwork(network);
+
             // Only rebuild cache if fairly small network
+            List<CableNetwork> remainingNetworks = List.of();
             if (network.getCableCount() <= 256) {
                 // Register networks that result from the removal of the cable, if any
-                var remainingNetworks = network.withoutCable(cablePos);
+                remainingNetworks = network.withoutCable(cablePos);
                 remainingNetworks.forEach(CableNetworkManager::addNetwork);
             }
+
+            // Notify all remaining networks to recompile their dependents
+            // (network topology changed, libraries may have become inaccessible)
+            for (CableNetwork remainingNetwork : remainingNetworks) {
+                remainingNetwork.invalidateAutoLabelsAndNotifyDependents();
+            }
+
+            // Notify library blocks that became completely disconnected from any network
+            for (BlockPos pos : libraryPositions) {
+                if (level.getBlockEntity(pos) instanceof LibraryBlockEntity library) {
+                    boolean stillOnNetwork = getNetworksForLevel(level)
+                            .anyMatch(net -> net.isAdjacentToCable(pos));
+                    if (!stillOnNetwork) {
+                        library.recompileAllDisks();
+                    }
+                }
+            }
+
+            // Notify managers that became completely disconnected from any network
+            for (BlockPos pos : managerPositions) {
+                if (level.getBlockEntity(pos) instanceof ManagerBlockEntity manager) {
+                    boolean stillOnNetwork = getNetworksForLevel(level)
+                            .anyMatch(net -> net.isAdjacentToCable(pos));
+                    if (!stillOnNetwork) {
+                        manager.rebuildProgramAndUpdateDisk();
+                    }
+                }
+            }
         });
     }
 

From eda119f99706afd67cb160514c0f5207a4489be8 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 17:28:14 +0100
Subject: [PATCH 26/33] feat: integrate LED indicator into disk slot

---
 .../render/LibraryBlockEntityRenderer.java    |  46 ++++++++++--------
 .../sfm/textures/block/library_front.png      | Bin 930 -> 849 bytes
 2 files changed, 27 insertions(+), 19 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java b/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java
index 8a09305a8..e97bad483 100644
--- a/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java
+++ b/src/main/java/ca/teamdman/sfm/client/render/LibraryBlockEntityRenderer.java
@@ -54,23 +54,28 @@ public class LibraryBlockEntityRenderer implements BlockEntityRenderer<LibraryBl
 
     // Layout constants based on 128x128 texture
     // Texture generator uses: GRID_START_X=4, ROW1_Y=48, ROW2_Y=72, COL_SPACING=25
-    // SLOT_WIDTH=16, SLOT_HEIGHT=6, LIGHT_SIZE=4
+    // Slot layout: [LED 4px][divider 1px][disk area 15px] = 20px total
     private static final float TEX = 128.0f;
 
     // Disk slot dimensions
-    private static final float SLOT_WIDTH = 16.0f / TEX;
+    private static final float LIGHT_SIZE_PX = 4.0f;
+    private static final float DISK_WIDTH_PX = 15.0f;
+    private static final float SLOT_WIDTH = (LIGHT_SIZE_PX + 1 + DISK_WIDTH_PX) / TEX;  // 20px total
     private static final float SLOT_HEIGHT = 6.0f / TEX;
     private static final float COL_SPACING = 25.0f / TEX;
     private static final float GRID_START_X = 4.0f / TEX;
     private static final float ROW1_Y = 48.0f / TEX;
     private static final float ROW2_Y = 72.0f / TEX;
 
-    // Indicator light position (right side of slot)
-    private static final float LIGHT_OFFSET_X = SLOT_WIDTH + 2.5f / TEX;
-    private static final float LIGHT_SIZE = 3.0f / TEX;
+    // Indicator light position (left side of slot, integrated)
+    private static final float LIGHT_SIZE = 4.0f / TEX;
     private static final float LIGHT_OFFSET_Y = (SLOT_HEIGHT - LIGHT_SIZE) / 2.0f;
 
-    // Disk line dimensions (thin red line inside slot)
+    // Disk area position (right side of slot, after LED + divider)
+    private static final float DISK_AREA_OFFSET_X = (LIGHT_SIZE_PX + 1) / TEX;
+    private static final float DISK_WIDTH = DISK_WIDTH_PX / TEX;
+
+    // Disk line dimensions (thin red line inside disk area)
     private static final float DISK_LINE_INSET = 1.0f / TEX;
     private static final float DISK_LINE_HEIGHT = 2.0f / TEX;
 
@@ -238,10 +243,13 @@ private void renderDiskLine(BufferBuilder buffer, Matrix4f matrix, int slot) {
         float slotX = GRID_START_X + col * COL_SPACING;
         float slotY = (row == 0) ? ROW1_Y : ROW2_Y;
 
-        // Thin red line inside the slot (representing disk edge)
+        // Disk area is on the right side of slot (after LED + divider)
+        float diskAreaX = slotX + DISK_AREA_OFFSET_X;
+
+        // Thin red line inside the disk area (representing disk edge)
         // Mirror X coordinate (1.0f - x) to match texture orientation on north face
-        float x1 = 1.0f - slotX - SLOT_WIDTH + DISK_LINE_INSET;
-        float x2 = 1.0f - slotX - DISK_LINE_INSET;
+        float x1 = 1.0f - diskAreaX - DISK_WIDTH + DISK_LINE_INSET;
+        float x2 = 1.0f - diskAreaX - DISK_LINE_INSET;
         float y1 = 1.0f - slotY - SLOT_HEIGHT / 2.0f - DISK_LINE_HEIGHT / 2.0f;
         float y2 = 1.0f - slotY - SLOT_HEIGHT / 2.0f + DISK_LINE_HEIGHT / 2.0f;
         float z = Z_OFFSET;
@@ -259,10 +267,10 @@ private void renderSlotIndicator(BufferBuilder buffer, Matrix4f matrix, int slot
         float slotX = GRID_START_X + col * COL_SPACING;
         float slotY = (row == 0) ? ROW1_Y : ROW2_Y;
 
-        // Light position is to the right of the disk slot in texture space
+        // LED is on the left side of slot (integrated)
         // Mirror X coordinate (1.0f - x) to match texture orientation on north face
-        float x1 = 1.0f - slotX - LIGHT_OFFSET_X - LIGHT_SIZE;
-        float x2 = 1.0f - slotX - LIGHT_OFFSET_X;
+        float x1 = 1.0f - slotX - LIGHT_SIZE;
+        float x2 = 1.0f - slotX;
         float y1 = 1.0f - slotY - LIGHT_OFFSET_Y - LIGHT_SIZE;
         float y2 = 1.0f - slotY - LIGHT_OFFSET_Y;
         float z = Z_OFFSET;
@@ -281,18 +289,18 @@ private void renderGlow(BufferBuilder buffer, Matrix4f matrix, int slot, float r
         float slotX = GRID_START_X + col * COL_SPACING;
         float slotY = (row == 0) ? ROW1_Y : ROW2_Y;
 
-        // Glow centered on the light position
+        // Glow centered on the LED (left side of slot)
         // Mirror X coordinate (1.0f - x) to match texture orientation on north face
-        float lightX = 1.0f - slotX - LIGHT_OFFSET_X - LIGHT_SIZE / 2.0f;
-        float lightY = slotY + LIGHT_OFFSET_Y + LIGHT_SIZE / 2.0f;
+        float lightCenterX = 1.0f - slotX - LIGHT_SIZE / 2.0f;
+        float lightCenterY = slotY + LIGHT_OFFSET_Y + LIGHT_SIZE / 2.0f;
 
         float glowSize = LIGHT_SIZE * GLOW_SIZE_MULTIPLIER;
         float halfGlow = glowSize / 2.0f;
 
-        float x1 = lightX - halfGlow;
-        float x2 = lightX + halfGlow;
-        float y1 = 1.0f - lightY - halfGlow;
-        float y2 = 1.0f - lightY + halfGlow;
+        float x1 = lightCenterX - halfGlow;
+        float x2 = lightCenterX + halfGlow;
+        float y1 = 1.0f - lightCenterY - halfGlow;
+        float y2 = 1.0f - lightCenterY + halfGlow;
         float z = Z_GLOW_OFFSET;
 
         // Semi-transparent glow quad
diff --git a/src/main/resources/assets/sfm/textures/block/library_front.png b/src/main/resources/assets/sfm/textures/block/library_front.png
index cfa498f6c9441f6077b5ff232bf92570ed49a161..7bd514868c5f0bceff91c93cb5c9b44673b6d92c 100644
GIT binary patch
literal 849
zcmeAS@N?(olHy`uVBq!ia0vp^4Is?H1|$#LC7xzrV3zQ7aSW-5dwa__@0Ejq>q8v|
z&SUqOy-%>+_+R(wiKD&a&*#%7=cT-wcTk-5QoyFy9*$o7)?I(iUsHQFUap`0j1JR|
z`|k~$7@lz)kYSvm%uvjdpeO5K-En^M&1|iP%vm2Auf%aKu-F>Tq~Z5=DnnOrwQ9qo
zD{;G73U=QuE3B(r_WY-9)_RtJ2Y=+YUe{xMum@fFTOo%(6NIR%66^%Ht4u`?{4uUs
zx8wX_#sz9j2JXmy>0>w}*kH+Iu$|+<@88ucDl=-<nWsHj%O;@xa_L@k<1OW9Z}244
z)$EM<m(5<k_-|IH_|cxF<>xcbFJ-Ezt2r{UyKDW~BsV$6HGAw9KjLAsSO6h<&N4iE
zUmdl3Ma8rAGbXAtODM)&;W%^RHc!G5vkH~8C%Q}>Qx}-wa0`+HyBQwM=dPaJe(ZTw
zvfI5ZhK-ZrZdDsQS6>HNaQys#_iKFr+<spb((jV=en0QxJa5(ye|~f*i;Kq3KH6i$
z6j530c2tt3zyV6kW;}EM`<Al6k7wcymHpWaoc62`oH22`<N=S|4<2VuM6(EJJLa+^
zzybxyA@~G$mN2|ku=7t_zmnlm{gg+>EA|RG6oTS>&Mj?5k>%gK7>=&o%g4E3@5gBs
za_b-c?Ro@C5}OqneJ*c#^`hGHRpozRqIl3!b<ZA{j4T$;`|b}+Nq#Gy{{<x`VPxs+
ziHvVLpMTW4w_ao3{l(v`Udu6@b4E&bM8vs1;{kET8Nb;J4jlCQd-uR>U{+!9boFyt
I=akR{04Sq%f&c&j

literal 930
zcmeAS@N?(olHy`uVBq!ia0vp^4Is?H1|$#LC7xzrV9xY(aSW-5dwc6*rnaGg+e49r
z4fD6NPk+F6r{4biBKAhx)i)=mN^bc)zg?eY?Sx5lnK@PJufP5(U-EY<|M};_No9<8
z-j{PIG8D2X^f4R}Y_MPwxGw8(x8w86nc3kCx3@iPS+rBgq3B`^r^3#Rbu1HNOv0Hw
z^k%)D!jQN9w&J(<-_P8sSDB^FsB!~H0Yx{gLsA747C&3+#qe#qNcZ30w#MJ(JD+(m
zaDD?)R;mnZv_bmB&rW5S)D09q=~_HjsNt{b(WL)%=g<6g2ie;MqWm}+UUxwhs5U&o
z>Kvd`pGuxPeeUyPh6%!q9m>ewac6kM;UL4<ahvr+h0U@};$mgzx4-#$=i%n(=FA&r
zyH%!FzE<9|dCynDdy)5kalF^buXTB?W8Uy9!R2pY((CG@vajz1elua-5u@iEr@!U=
z8}rop-yikWU6f^c5U{hEK}M@wpuzcRUmC;H&-qulZSQP6CwrD5?ZdfG*W4>m%<i}r
znfh)wL)s?sYx*f_)pq4S-u&Fn@P_S)8`OnZoedVu6L0wY`Qi3At*v)I>q2y%Wq7kJ
z5borb@@d=c4q2a$mcM9qns<SnL}2}t8^7WTk6V>bu>~r%7x-4S_k!K#`%`M~bzA>(
z1-qG#sbIw&M+UyB*0UI=oZla)|D^z^-h_F^L6AWY=RRHAkMKrR`qZ88nP!}fi`YM5
zCM5jcGi{KbAdMrqaeHQ+b;B;f=a-GIuVZ*qKjV=M));;5&$NQQ`c2)Q&F@cd`rYqR
ztXn5^U|X*5{CP_=p8W=;7w%a<{{gigXiD3+ADHGgESULTADEzYP^ACqG$@zZ-@Exe
x^(H7OiCtzsV1?B_oGEC>c7_Gr3`hR5uf2caf!8$eFTlLV;OXk;vd$@?2>^h~p{4);


From f64970dd77b390d09de725f0b033cd215e190092 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 18:01:26 +0100
Subject: [PATCH 27/33] fix: notify disconnected blocks when cable is removed

---
 .../cablenetwork/CableNetworkManager.java     | 52 ++++++++++---------
 1 file changed, 27 insertions(+), 25 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java
index acd27c8e7..118d78fb6 100644
--- a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java
+++ b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java
@@ -105,12 +105,6 @@ public static void onCablePlaced(Level level, BlockPos pos) {
 
     public static void onCableRemoved(Level level, BlockPos cablePos) {
         getNetworkFromCablePosition(level, cablePos).ifPresent(network -> {
-            // Capture library and manager positions before invalidating the network
-            Set<BlockPos> libraryPositions = network.getOrRebuildAutoLabels()
-                    .getPositions(LibraryBlockEntity.LIBRARY_LABEL);
-            Set<BlockPos> managerPositions = network.getOrRebuildAutoLabels()
-                    .getPositions(ManagerBlockEntity.MANAGER_LABEL);
-
             // Invalidate the original network
             removeNetwork(network);
 
@@ -127,29 +121,37 @@ public static void onCableRemoved(Level level, BlockPos cablePos) {
             for (CableNetwork remainingNetwork : remainingNetworks) {
                 remainingNetwork.invalidateAutoLabelsAndNotifyDependents();
             }
+        });
 
-            // Notify library blocks that became completely disconnected from any network
-            for (BlockPos pos : libraryPositions) {
-                if (level.getBlockEntity(pos) instanceof LibraryBlockEntity library) {
-                    boolean stillOnNetwork = getNetworksForLevel(level)
-                            .anyMatch(net -> net.isAdjacentToCable(pos));
-                    if (!stillOnNetwork) {
-                        library.recompileAllDisks();
-                    }
-                }
-            }
+        // Always notify blocks adjacent to the removed cable, after network changes are complete
+        // This handles both networked and standalone cables
+        notifyBlocksAdjacentToRemovedCable(level, cablePos);
+    }
 
-            // Notify managers that became completely disconnected from any network
-            for (BlockPos pos : managerPositions) {
-                if (level.getBlockEntity(pos) instanceof ManagerBlockEntity manager) {
-                    boolean stillOnNetwork = getNetworksForLevel(level)
-                            .anyMatch(net -> net.isAdjacentToCable(pos));
-                    if (!stillOnNetwork) {
-                        manager.rebuildProgramAndUpdateDisk();
-                    }
+    /**
+     * Notifies libraries and managers directly adjacent to a removed cable.
+     * Called regardless of whether a network existed, to handle standalone cables.
+     */
+    private static void notifyBlocksAdjacentToRemovedCable(Level level, BlockPos cablePos) {
+        BlockPos.MutableBlockPos adjacentPos = new BlockPos.MutableBlockPos();
+        for (Direction direction : SFMDirections.DIRECTIONS_WITHOUT_NULL) {
+            adjacentPos.set(cablePos).move(direction);
+            if (level.getBlockEntity(adjacentPos) instanceof LibraryBlockEntity library) {
+                // Check if this library is still connected to any network
+                boolean stillOnNetwork = getNetworksForLevel(level)
+                        .anyMatch(net -> net.isAdjacentToCable(adjacentPos));
+                if (!stillOnNetwork) {
+                    library.recompileAllDisks();
+                }
+            } else if (level.getBlockEntity(adjacentPos) instanceof ManagerBlockEntity manager) {
+                // Check if this manager is still connected to any network
+                boolean stillOnNetwork = getNetworksForLevel(level)
+                        .anyMatch(net -> net.isAdjacentToCable(adjacentPos));
+                if (!stillOnNetwork) {
+                    manager.rebuildProgramAndUpdateDisk();
                 }
             }
-        });
+        }
     }
 
     public static void purgeCableNetworkForManager(ManagerBlockEntity manager) {

From f5cb7a21eca1d4a585a2026571ee83d542204035 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 19:02:00 +0100
Subject: [PATCH 28/33] fix: ensure network discovery on world reload and batch
 notifications

---
 .../sfm/common/block/LibraryBlock.java        |  2 +-
 .../blockentity/LibraryBlockEntity.java       | 29 ++++---
 .../sfm/common/cablenetwork/CableNetwork.java | 87 +++++++++----------
 .../cablenetwork/CableNetworkManager.java     | 44 ++++++++++
 4 files changed, 102 insertions(+), 60 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java b/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java
index 6f1183fdf..f257a5600 100644
--- a/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java
+++ b/src/main/java/ca/teamdman/sfm/common/block/LibraryBlock.java
@@ -109,7 +109,7 @@ public void onPlace(
         if (!level.isClientSide()) {
             CableNetworkManager.getNetworksForLevel(level)
                     .filter(network -> network.isAdjacentToCable(pos))
-                    .forEach(CableNetwork::invalidateAutoLabelsAndNotifyManagers);
+                    .forEach(CableNetwork::invalidateAutoLabelsAndNotifyDependents);
         }
     }
 
diff --git a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
index 82e52138e..6e9bae047 100644
--- a/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
+++ b/src/main/java/ca/teamdman/sfm/common/blockentity/LibraryBlockEntity.java
@@ -157,10 +157,11 @@ public LibraryResolver createLibraryResolver() {
             return createLocalLibraryResolver(new HashSet<>());
         }
 
-        // Find the cable network this library is adjacent to
-        Optional<CableNetwork> networkOpt = CableNetworkManager.getNetworksForLevel(level)
-                .filter(network -> network.isAdjacentToCable(worldPosition))
-                .findFirst();
+        // Get or register the cable network at this position
+        // LibraryBlock implements ICableBlock, so it IS a cable
+        // This ensures network discovery happens even after world reload
+        Optional<CableNetwork> networkOpt = CableNetworkManager
+                .getOrRegisterNetworkFromCablePosition(level, worldPosition);
 
         if (networkOpt.isEmpty()) {
             // Not connected to network: only resolve from this library block's disks
@@ -314,16 +315,18 @@ public void setChanged() {
     private void notifyNetworkLibraryChanged() {
         if (level == null || level.isClientSide()) return;
 
-        // Find networks adjacent to this library block and notify them
-        boolean onNetwork = CableNetworkManager.getNetworksForLevel(level)
-                .filter(network -> network.isAdjacentToCable(worldPosition))
-                .peek(CableNetwork::invalidateAutoLabelsAndNotifyDependents)
-                .findAny()
-                .isPresent();
+        // Get or register the cable network at this position
+        // LibraryBlock implements ICableBlock, so it IS a cable
+        // This ensures network discovery happens even after world reload
+        Optional<CableNetwork> networkOpt = CableNetworkManager
+                .getOrRegisterNetworkFromCablePosition(level, worldPosition);
 
-        // If not on a network, recompile local disks to update errors
-        // (e.g., resolved circular dependencies)
-        if (!onNetwork) {
+        if (networkOpt.isPresent()) {
+            // On a network: notify dependents to recompile
+            networkOpt.get().invalidateAutoLabelsAndNotifyDependents();
+        } else {
+            // Not on a network: recompile local disks to update errors
+            // (e.g., resolved circular dependencies)
             recompileAllDisks();
         }
     }
diff --git a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
index 406234aaa..ab9228860 100644
--- a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
+++ b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
@@ -42,15 +42,15 @@ public class CableNetwork {
     private @Nullable LabelPositionHolder autoLabelCache = null;
 
     /**
-     * Tracks the last game tick when manager notifications were sent.
-     * Used for debouncing rapid library changes.
+     * Tracks the tick when a delayed notification should fire.
+     * Set to -1 when no notification is pending.
      */
-    private long lastNotificationTick = -1;
+    private long pendingNotificationTick = -1;
 
     /**
-     * Minimum ticks between manager notifications to prevent excessive rebuilds.
+     * Delay in ticks before a batched notification fires.
      */
-    private static final int NOTIFICATION_DEBOUNCE_TICKS = 5;
+    private static final int NOTIFICATION_DELAY_TICKS = 5;
 
     public CableNetwork(Level level) {
         this.level = level;
@@ -293,61 +293,42 @@ public void invalidateAutoLabelCache() {
     }
 
     /**
-     * Invalidates the auto-label cache and notifies all managers on this network
-     * to re-validate their programs. Call this when library blocks are added/removed.
-     *
-     * Notifications are debounced to prevent excessive program rebuilds when
-     * multiple library changes occur in quick succession (e.g., inserting multiple disks).
+     * Invalidates the auto-label cache and schedules a delayed notification to all
+     * managers and library blocks on this network. Multiple rapid calls will reset
+     * the delay, ensuring only the final state is processed.
      */
-    public void invalidateAutoLabelsAndNotifyManagers() {
-        // Get manager positions BEFORE invalidating the cache
-        Set<BlockPos> managerPositions = getOrRebuildAutoLabels()
-                .getPositions(ManagerBlockEntity.MANAGER_LABEL);
-
-        // Now invalidate the cache
+    public void invalidateAutoLabelsAndNotifyDependents() {
+        // Invalidate the cache immediately
         autoLabelCache = null;
 
-        // Check debounce - skip notification if within debounce window
+        // Schedule notification after delay (resets if called again)
         long currentTick = level.getGameTime();
-        if (lastNotificationTick >= 0 && currentTick - lastNotificationTick < NOTIFICATION_DEBOUNCE_TICKS) {
-            // Cache is already invalidated, managers will get fresh data on next tick
-            return;
-        }
-        lastNotificationTick = currentTick;
+        pendingNotificationTick = currentTick + NOTIFICATION_DELAY_TICKS;
 
-        // Notify all managers to re-validate their programs
-        for (BlockPos pos : managerPositions) {
-            if (level.getBlockEntity(pos) instanceof ManagerBlockEntity manager) {
-                manager.rebuildProgramAndUpdateDisk();
-            }
-        }
+        // Register this network for delayed processing
+        CableNetworkManager.schedulePendingNotification(this);
     }
 
     /**
-     * Invalidates the auto-label cache and notifies all managers and library blocks
-     * on this network to recompile. Call this when library disk contents change.
-     *
-     * Notifications are debounced to prevent excessive program rebuilds when
-     * multiple library changes occur in quick succession.
+     * Called by CableNetworkManager when the pending notification delay has elapsed.
+     * Sends notifications to all managers and libraries on the network.
      */
-    public void invalidateAutoLabelsAndNotifyDependents() {
-        // Get positions BEFORE invalidating the cache
+    public void processPendingNotification() {
+        long currentTick = level.getGameTime();
+        if (pendingNotificationTick < 0 || currentTick < pendingNotificationTick) {
+            // Not yet time, or no pending notification
+            return;
+        }
+
+        // Clear pending state
+        pendingNotificationTick = -1;
+
+        // Get current positions (cache was already invalidated)
         Set<BlockPos> managerPositions = getOrRebuildAutoLabels()
                 .getPositions(ManagerBlockEntity.MANAGER_LABEL);
         Set<BlockPos> libraryPositions = getOrRebuildAutoLabels()
                 .getPositions(LibraryBlockEntity.LIBRARY_LABEL);
 
-        // Now invalidate the cache
-        autoLabelCache = null;
-
-        // Check debounce - skip notification if within debounce window
-        long currentTick = level.getGameTime();
-        if (lastNotificationTick >= 0 && currentTick - lastNotificationTick < NOTIFICATION_DEBOUNCE_TICKS) {
-            // Cache is already invalidated, dependents will get fresh data on next tick
-            return;
-        }
-        lastNotificationTick = currentTick;
-
         // Notify all managers to re-validate their programs
         for (BlockPos pos : managerPositions) {
             if (level.getBlockEntity(pos) instanceof ManagerBlockEntity manager) {
@@ -363,6 +344,20 @@ public void invalidateAutoLabelsAndNotifyDependents() {
         }
     }
 
+    /**
+     * @return true if this network has a pending notification scheduled
+     */
+    public boolean hasPendingNotification() {
+        return pendingNotificationTick >= 0;
+    }
+
+    /**
+     * @return the tick when the pending notification should fire, or -1 if none
+     */
+    public long getPendingNotificationTick() {
+        return pendingNotificationTick;
+    }
+
     /**
      * Discover what networks would exist if this network did not have a cable at {@code cablePos}.
      *
diff --git a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java
index 118d78fb6..5061e28f4 100644
--- a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java
+++ b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java
@@ -13,12 +13,14 @@
 import net.minecraft.server.level.ServerLevel;
 import net.minecraft.world.level.Level;
 import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraftforge.event.TickEvent;
 import net.minecraftforge.event.level.ChunkEvent;
 import net.minecraftforge.event.level.LevelEvent;
 import net.minecraftforge.eventbus.api.SubscribeEvent;
 import net.minecraftforge.fml.common.Mod;
 
 import java.util.*;
+import java.util.concurrent.ConcurrentHashMap;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
@@ -44,6 +46,7 @@
 public class CableNetworkManager {
     private static final Map<Level, Long2ObjectMap<CableNetwork>> NETWORKS_BY_CABLE_POSITION = new Object2ObjectOpenHashMap<>();
     private static final Map<Level, List<CableNetwork>> NETWORKS_BY_LEVEL = new Object2ObjectOpenHashMap<>();
+    private static final Set<CableNetwork> NETWORKS_WITH_PENDING_NOTIFICATIONS = ConcurrentHashMap.newKeySet();
 
     /**
      * For diagnostics, called when a lookup map has changed
@@ -99,6 +102,7 @@ public static void onCablePlaced(Level level, BlockPos pos) {
         if (level.isClientSide()) return;
         getOrRegisterNetworkFromCablePosition(level, pos).ifPresent(network -> {
             // Invalidate and rebuild auto labels to discover newly connected blocks
+            // Uses delayed notification to batch rapid changes
             network.invalidateAutoLabelsAndNotifyDependents();
         });
     }
@@ -118,6 +122,7 @@ public static void onCableRemoved(Level level, BlockPos cablePos) {
 
             // Notify all remaining networks to recompile their dependents
             // (network topology changed, libraries may have become inaccessible)
+            // Uses delayed notification to batch rapid changes
             for (CableNetwork remainingNetwork : remainingNetworks) {
                 remainingNetwork.invalidateAutoLabelsAndNotifyDependents();
             }
@@ -311,6 +316,45 @@ public static void onLevelUnload(LevelEvent.Unload event) {
         if (!(event.getLevel() instanceof ServerLevel level)) return;
         NETWORKS_BY_LEVEL.remove(level);
         NETWORKS_BY_CABLE_POSITION.remove(level);
+        // Remove any pending notifications for this level
+        NETWORKS_WITH_PENDING_NOTIFICATIONS.removeIf(net -> net.getLevel() == level);
+    }
+
+    @SubscribeEvent
+    public static void onServerTick(TickEvent.ServerTickEvent event) {
+        if (event.phase != TickEvent.Phase.END) return;
+        processPendingNotifications();
+    }
+
+    /**
+     * Registers a network for delayed notification processing.
+     * Called by CableNetwork when a notification is scheduled.
+     */
+    public static void schedulePendingNotification(CableNetwork network) {
+        NETWORKS_WITH_PENDING_NOTIFICATIONS.add(network);
+    }
+
+    /**
+     * Processes all networks with pending notifications that are ready to fire.
+     */
+    private static void processPendingNotifications() {
+        if (NETWORKS_WITH_PENDING_NOTIFICATIONS.isEmpty()) return;
+
+        Iterator<CableNetwork> iterator = NETWORKS_WITH_PENDING_NOTIFICATIONS.iterator();
+        while (iterator.hasNext()) {
+            CableNetwork network = iterator.next();
+            long pendingTick = network.getPendingNotificationTick();
+            if (pendingTick < 0) {
+                // No longer pending
+                iterator.remove();
+                continue;
+            }
+            long currentTick = network.getLevel().getGameTime();
+            if (currentTick >= pendingTick) {
+                network.processPendingNotification();
+                iterator.remove();
+            }
+        }
     }
 
     public static void purgeChunkFromCableNetworks(ServerLevel level, ChunkAccess chunkAccess) {

From 095bb5d67337198ee9685f0901bb0f39eb049f1e Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Sun, 25 Jan 2026 22:23:51 +0100
Subject: [PATCH 29/33] fix: recompile library disks when isolated from network

---
 ...ibraryRecompileOnCableRemovalGameTest.java | 111 ++++++++++++++++++
 .../struct/MacroBasicExpansionGameTest.java   |   2 +-
 .../struct/MacroWithStructAccessGameTest.java |   2 +-
 .../sfm/common/cablenetwork/CableNetwork.java |   7 +-
 .../cablenetwork/CableNetworkManager.java     |  30 +++--
 5 files changed, 137 insertions(+), 15 deletions(-)
 create mode 100644 src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryRecompileOnCableRemovalGameTest.java

diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryRecompileOnCableRemovalGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryRecompileOnCableRemovalGameTest.java
new file mode 100644
index 000000000..c3a8f34e4
--- /dev/null
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryRecompileOnCableRemovalGameTest.java
@@ -0,0 +1,111 @@
+package ca.teamdman.sfm.gametest.tests.library;
+
+import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
+import ca.teamdman.sfm.common.item.DiskItem;
+import ca.teamdman.sfm.common.registry.SFMBlocks;
+import ca.teamdman.sfm.common.registry.SFMItems;
+import ca.teamdman.sfm.gametest.SFMGameTest;
+import ca.teamdman.sfm.gametest.SFMGameTestDefinition;
+import ca.teamdman.sfm.gametest.SFMGameTestHelper;
+import net.minecraft.core.BlockPos;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.block.Blocks;
+
+import static ca.teamdman.sfm.gametest.SFMGameTestMethodHelpers.assertTrue;
+
+/**
+ * Tests that library disks are recompiled when the only network connection
+ * (cable) next to the library is removed.
+ * <p>
+ * Setup:
+ * - Library A has a disk that uses library "provider"
+ * - Library B has a disk with NAME "provider" containing definitions
+ * - A cable connects them
+ * <p>
+ * Test:
+ * 1. Initially, Library A's disk should have no errors (can resolve "provider")
+ * 2. Remove the cable connecting them
+ * 3. After the 5-tick notification delay, Library A's disk should have errors
+ *    (cannot resolve "provider" anymore, proving recompilation occurred)
+ */
+@SuppressWarnings({
+        "RedundantSuppression",
+        "DataFlowIssue",
+        "OptionalGetWithoutIsPresent",
+        "DuplicatedCode",
+        "ArraysAsListWithZeroOrOneArgument"
+})
+@SFMGameTest
+public class LibraryRecompileOnCableRemovalGameTest extends SFMGameTestDefinition {
+
+    @Override
+    public String template() {
+        return "3x2x1";
+    }
+
+    @Override
+    public void run(SFMGameTestHelper helper) {
+        // Place two library blocks with a cable between them
+        // Layout: [LibraryA] - [Cable] - [LibraryB]
+        BlockPos libraryAPos = new BlockPos(0, 2, 0);
+        BlockPos cablePos = new BlockPos(1, 2, 0);
+        BlockPos libraryBPos = new BlockPos(2, 2, 0);
+
+        helper.setBlock(libraryAPos, SFMBlocks.LIBRARY_BLOCK.get());
+        helper.setBlock(cablePos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(libraryBPos, SFMBlocks.LIBRARY_BLOCK.get());
+
+        // Get library block entities
+        LibraryBlockEntity libraryA = (LibraryBlockEntity) helper.getBlockEntity(libraryAPos);
+        LibraryBlockEntity libraryB = (LibraryBlockEntity) helper.getBlockEntity(libraryBPos);
+
+        // Create disk for Library B with a named library definition
+        ItemStack providerDisk = new ItemStack(SFMItems.DISK_ITEM.get());
+        DiskItem.setProgram(providerDisk, """
+                NAME "provider"
+
+                -- This library provides a simple macro
+                macro greet()
+                    -- just a placeholder
+                end
+                """);
+
+        // Create disk for Library A that uses the provider library
+        ItemStack consumerDisk = new ItemStack(SFMItems.DISK_ITEM.get());
+        DiskItem.setProgram(consumerDisk, """
+                NAME "consumer"
+
+                USE LIBRARY "provider"
+                """);
+
+        // Insert disks into libraries
+        libraryB.setItem(0, providerDisk);
+        libraryA.setItem(0, consumerDisk);
+
+        // Wait a moment for initial compilation via the batched notification system
+        helper.runAfterDelay(10, () -> {
+            // Get the consumer disk and check it has no errors (library was found)
+            ItemStack diskAfterConnect = libraryA.getItem(0);
+            assertTrue(
+                    DiskItem.getErrors(diskAfterConnect).isEmpty(),
+                    "Consumer disk should have no errors when connected to provider library"
+            );
+
+            // Now remove the cable, disconnecting Library A from Library B
+            helper.setBlock(cablePos, Blocks.AIR);
+
+            // Wait for the 5-tick notification delay plus a small buffer
+            helper.runAfterDelay(10, () -> {
+                // Get the consumer disk and verify it now has errors
+                // (library "provider" cannot be resolved anymore)
+                ItemStack diskAfterDisconnect = libraryA.getItem(0);
+                assertTrue(
+                        !DiskItem.getErrors(diskAfterDisconnect).isEmpty(),
+                        "Consumer disk should have errors after disconnection (library not found)"
+                );
+
+                helper.succeed();
+            });
+        });
+    }
+}
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroBasicExpansionGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroBasicExpansionGameTest.java
index 881e3bad7..9f626695f 100644
--- a/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroBasicExpansionGameTest.java
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroBasicExpansionGameTest.java
@@ -34,7 +34,7 @@ macro transfer(source, dest)
                 end
 
                 every 20 ticks do
-                    expand transfer(left, right)
+                    do transfer(left, right)
                 end
                 """);
         test.preContents("left", Arrays.asList(
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroWithStructAccessGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroWithStructAccessGameTest.java
index b81d7a519..12aea8532 100644
--- a/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroWithStructAccessGameTest.java
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroWithStructAccessGameTest.java
@@ -47,7 +47,7 @@ macro process(machine: Container, source, dest)
                 let storage = Chest { label: "left" }
 
                 every 20 ticks do
-                    expand process(storage, left, right)
+                    do process(storage, left, right)
                 end
                 """);
         test.preContents("left", Arrays.asList(
diff --git a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
index ab9228860..de6043d02 100644
--- a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
+++ b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetwork.java
@@ -246,7 +246,7 @@ public LabelPositionHolder getOrRebuildAutoLabels() {
 
         autoLabelCache = LabelPositionHolder.empty();
 
-        // Discover managers (which are cables) and library blocks (adjacent to cables)
+        // Discover managers and libraries (which can be cables themselves) and adjacent blocks
         LongSet visitedAdjacent = new LongOpenHashSet();
         BlockPos.MutableBlockPos target = new BlockPos.MutableBlockPos();
 
@@ -258,6 +258,11 @@ public LabelPositionHolder getOrRebuildAutoLabels() {
                 autoLabelCache.add(ManagerBlockEntity.MANAGER_LABEL, cablePos);
             }
 
+            // Check if the cable itself is a library (LibraryBlock implements ICableBlock)
+            if (level.getBlockEntity(cablePos) instanceof LibraryBlockEntity) {
+                autoLabelCache.add(LibraryBlockEntity.LIBRARY_LABEL, cablePos);
+            }
+
             // Check adjacent positions for library blocks
             for (Direction direction : SFMDirections.DIRECTIONS_WITHOUT_NULL) {
                 target.set(cablePos).move(direction);
diff --git a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java
index 5061e28f4..ce59d1a8b 100644
--- a/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java
+++ b/src/main/java/ca/teamdman/sfm/common/cablenetwork/CableNetworkManager.java
@@ -141,19 +141,25 @@ private static void notifyBlocksAdjacentToRemovedCable(Level level, BlockPos cab
         BlockPos.MutableBlockPos adjacentPos = new BlockPos.MutableBlockPos();
         for (Direction direction : SFMDirections.DIRECTIONS_WITHOUT_NULL) {
             adjacentPos.set(cablePos).move(direction);
-            if (level.getBlockEntity(adjacentPos) instanceof LibraryBlockEntity library) {
-                // Check if this library is still connected to any network
-                boolean stillOnNetwork = getNetworksForLevel(level)
-                        .anyMatch(net -> net.isAdjacentToCable(adjacentPos));
-                if (!stillOnNetwork) {
-                    library.recompileAllDisks();
+            if (level.getBlockEntity(adjacentPos) instanceof LibraryBlockEntity) {
+                // Check if this library is still connected to a meaningful network
+                // (one with other cables besides just the library itself)
+                boolean stillOnMeaningfulNetwork = getNetworksForLevel(level)
+                        .anyMatch(net -> net.containsCablePosition(adjacentPos) && net.getCableCount() > 1);
+                if (!stillOnMeaningfulNetwork) {
+                    // Library is isolated - notify via its own network (batched) to recompile
+                    getOrRegisterNetworkFromCablePosition(level, adjacentPos.immutable())
+                            .ifPresent(CableNetwork::invalidateAutoLabelsAndNotifyDependents);
                 }
-            } else if (level.getBlockEntity(adjacentPos) instanceof ManagerBlockEntity manager) {
-                // Check if this manager is still connected to any network
-                boolean stillOnNetwork = getNetworksForLevel(level)
-                        .anyMatch(net -> net.isAdjacentToCable(adjacentPos));
-                if (!stillOnNetwork) {
-                    manager.rebuildProgramAndUpdateDisk();
+            } else if (level.getBlockEntity(adjacentPos) instanceof ManagerBlockEntity) {
+                // Check if this manager is still connected to a meaningful network
+                // (one with other cables besides just the manager itself)
+                boolean stillOnMeaningfulNetwork = getNetworksForLevel(level)
+                        .anyMatch(net -> net.containsCablePosition(adjacentPos) && net.getCableCount() > 1);
+                if (!stillOnMeaningfulNetwork) {
+                    // Manager is isolated - notify via its own network (batched) to rebuild
+                    getOrRegisterNetworkFromCablePosition(level, adjacentPos.immutable())
+                            .ifPresent(CableNetwork::invalidateAutoLabelsAndNotifyDependents);
                 }
             }
         }

From eb31736f0c8370579de17ca2b08fe27efc8e83c0 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Mon, 26 Jan 2026 00:09:30 +0100
Subject: [PATCH 30/33] test: add library and definitions tests

---
 .../LibraryChainedImportsGameTest.java        | 217 +++++++++++++
 ...yProtocolConstraintValidationGameTest.java | 146 +++++++++
 ...LibraryWithCombinedIOProtocolGameTest.java | 178 +++++++++++
 .../LibraryWithStructIOProtocolsGameTest.java | 176 +++++++++++
 .../LibraryWithTransferMacroGameTest.java     | 181 +++++++++++
 .../ca/teamdman/sfml/SFMLTestHelpers.java     |  92 +++++-
 src/test/java/ca/teamdman/sfml/SFMLTests.java | 284 ++++++++++++++++++
 7 files changed, 1270 insertions(+), 4 deletions(-)
 create mode 100644 src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryChainedImportsGameTest.java
 create mode 100644 src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryProtocolConstraintValidationGameTest.java
 create mode 100644 src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithCombinedIOProtocolGameTest.java
 create mode 100644 src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithStructIOProtocolsGameTest.java
 create mode 100644 src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithTransferMacroGameTest.java

diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryChainedImportsGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryChainedImportsGameTest.java
new file mode 100644
index 000000000..25e734ae3
--- /dev/null
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryChainedImportsGameTest.java
@@ -0,0 +1,217 @@
+package ca.teamdman.sfm.gametest.tests.library;
+
+import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
+import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
+import ca.teamdman.sfm.common.item.DiskItem;
+import ca.teamdman.sfm.common.label.LabelPositionHolder;
+import ca.teamdman.sfm.common.registry.SFMBlocks;
+import ca.teamdman.sfm.common.registry.SFMItems;
+import ca.teamdman.sfm.gametest.SFMGameTest;
+import ca.teamdman.sfm.gametest.SFMGameTestDefinition;
+import ca.teamdman.sfm.gametest.SFMGameTestHelper;
+import net.minecraft.core.BlockPos;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.block.Blocks;
+
+import static ca.teamdman.sfm.gametest.SFMGameTestCountHelpers.count;
+import static ca.teamdman.sfm.gametest.SFMGameTestMethodHelpers.assertTrue;
+
+/**
+ * Tests chained library imports where multiple libraries depend on each other.
+ * <p>
+ * Setup:
+ * - base_protocols library: defines HasInput and HasOutput protocols
+ * - struct_lib library: imports base_protocols, defines Furnace struct
+ * - macro_lib library: imports base_protocols and struct_lib, defines smelt macro
+ * - Manager: imports all three libraries and uses the smelt macro
+ * <p>
+ * This tests that:
+ * 1. Libraries can import other libraries
+ * 2. Definitions are properly resolved across the chain
+ * 3. Protocol constraints work with chained imports
+ */
+@SuppressWarnings({
+        "RedundantSuppression",
+        "DataFlowIssue",
+        "OptionalGetWithoutIsPresent",
+        "DuplicatedCode"
+})
+@SFMGameTest
+public class LibraryChainedImportsGameTest extends SFMGameTestDefinition {
+
+    @Override
+    public String template() {
+        return "7x3x3";
+    }
+
+    @Override
+    public int maxTicks() {
+        return 200;
+    }
+
+    @Override
+    public void run(SFMGameTestHelper helper) {
+        // Layout (y=2 front row): [ore] - [baseLib] - [structLib] - [Manager] - [macroLib] - [furnace] - [ingots]
+        // Layout (y=2 back row):  [cable] - [cable] - [cable]     - [cable]   - [cable]    - [cable]   - [cable]
+        BlockPos orePos = new BlockPos(0, 2, 0);
+        BlockPos baseLibPos = new BlockPos(1, 2, 0);
+        BlockPos structLibPos = new BlockPos(2, 2, 0);
+        BlockPos managerPos = new BlockPos(3, 2, 0);
+        BlockPos macroLibPos = new BlockPos(4, 2, 0);
+        BlockPos furnacePos = new BlockPos(5, 2, 0);
+        BlockPos ingotsPos = new BlockPos(6, 2, 0);
+
+        // Cable row behind to connect everything
+        BlockPos cable0Pos = new BlockPos(0, 2, 1);
+        BlockPos cable1Pos = new BlockPos(1, 2, 1);
+        BlockPos cable2Pos = new BlockPos(2, 2, 1);
+        BlockPos cable3Pos = new BlockPos(3, 2, 1);
+        BlockPos cable4Pos = new BlockPos(4, 2, 1);
+        BlockPos cable5Pos = new BlockPos(5, 2, 1);
+        BlockPos cable6Pos = new BlockPos(6, 2, 1);
+
+        // Place main blocks
+        helper.setBlock(orePos, SFMBlocks.TEST_BARREL_BLOCK.get());
+        helper.setBlock(baseLibPos, SFMBlocks.LIBRARY_BLOCK.get());
+        helper.setBlock(structLibPos, SFMBlocks.LIBRARY_BLOCK.get());
+        helper.setBlock(managerPos, SFMBlocks.MANAGER_BLOCK.get());
+        helper.setBlock(macroLibPos, SFMBlocks.LIBRARY_BLOCK.get());
+        helper.setBlock(furnacePos, SFMBlocks.TEST_BARREL_BLOCK.get());
+        helper.setBlock(ingotsPos, SFMBlocks.TEST_BARREL_BLOCK.get());
+
+        // Place cable row behind
+        helper.setBlock(cable0Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable1Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable2Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable3Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable4Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable5Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable6Pos, SFMBlocks.CABLE_BLOCK.get());
+
+        // Get block entities
+        LibraryBlockEntity baseLib = (LibraryBlockEntity) helper.getBlockEntity(baseLibPos);
+        LibraryBlockEntity structLib = (LibraryBlockEntity) helper.getBlockEntity(structLibPos);
+        LibraryBlockEntity macroLib = (LibraryBlockEntity) helper.getBlockEntity(macroLibPos);
+        ManagerBlockEntity manager = (ManagerBlockEntity) helper.getBlockEntity(managerPos);
+
+        // Create base_protocols library disk
+        ItemStack baseLibDisk = new ItemStack(SFMItems.DISK_ITEM.get());
+        DiskItem.setProgram(baseLibDisk, """
+                NAME "base_protocols"
+
+                protocol HasInput
+                    input: sidequalifier slotqualifier
+                end
+
+                protocol HasOutput
+                    output: sidequalifier slotqualifier
+                end
+                """);
+        baseLib.setItem(0, baseLibDisk);
+
+        // Create struct_lib library disk
+        ItemStack structLibDisk = new ItemStack(SFMItems.DISK_ITEM.get());
+        DiskItem.setProgram(structLibDisk, """
+                NAME "struct_lib"
+                use library "base_protocols"
+
+                struct Furnace : HasInput, HasOutput
+                    input: EACH SIDE SLOTS 0-8
+                    output: EACH SIDE SLOTS 9-17
+                end
+                """);
+        structLib.setItem(0, structLibDisk);
+
+        // Create macro_lib library disk
+        ItemStack macroLibDisk = new ItemStack(SFMItems.DISK_ITEM.get());
+        DiskItem.setProgram(macroLibDisk, """
+                NAME "macro_lib"
+                use library "base_protocols"
+                use library "struct_lib"
+
+                macro smelt(machine: HasInput, machine2: HasOutput, src, dst)
+                    input from src
+                    output to machine using input
+                    forget
+                    input from machine2 using output
+                    output to dst
+                end
+                """);
+        macroLib.setItem(0, macroLibDisk);
+
+        // Create manager disk that imports all libraries
+        manager.setItem(0, new ItemStack(SFMItems.DISK_ITEM.get()));
+        manager.setProgram("""
+                NAME "Chained Manager"
+                use library "base_protocols"
+                use library "struct_lib"
+                use library "macro_lib"
+
+                let furnace = Furnace { label: "furnace" }
+                every 20 ticks do
+                    DO smelt(furnace, furnace, ore_chest, ingot_chest)
+                end
+                """);
+
+        // Setup labels
+        LabelPositionHolder labelHolder = LabelPositionHolder.empty()
+                .add("ore_chest", helper.absolutePos(orePos))
+                .add("furnace", helper.absolutePos(furnacePos))
+                .add("ingot_chest", helper.absolutePos(ingotsPos));
+        labelHolder.save(manager.getDisk());
+
+        // Put ore in source
+        var oreHandler = helper.getItemHandler(orePos);
+        oreHandler.insertItem(0, new ItemStack(Blocks.GOLD_ORE, 32), false);
+
+        // Put ingots in furnace output (simulating smelting)
+        var furnaceHandler = helper.getItemHandler(furnacePos);
+        furnaceHandler.insertItem(9, new ItemStack(Blocks.GOLD_BLOCK, 4), false);
+
+        // Wait for libraries to compile and manager to run
+        helper.runAfterDelay(20, () -> {
+            // Verify all library disks have no errors
+            assertTrue(
+                    DiskItem.getErrors(baseLib.getItem(0)).isEmpty(),
+                    "base_protocols library should have no errors but had: " + DiskItem.getErrors(baseLib.getItem(0))
+            );
+            assertTrue(
+                    DiskItem.getErrors(structLib.getItem(0)).isEmpty(),
+                    "struct_lib library should have no errors but had: " + DiskItem.getErrors(structLib.getItem(0))
+            );
+            assertTrue(
+                    DiskItem.getErrors(macroLib.getItem(0)).isEmpty(),
+                    "macro_lib library should have no errors but had: " + DiskItem.getErrors(macroLib.getItem(0))
+            );
+
+            // Verify manager disk has no errors
+            assertTrue(
+                    DiskItem.getErrors(manager.getDisk()).isEmpty(),
+                    "Manager disk should have no errors but had: " + DiskItem.getErrors(manager.getDisk())
+            );
+
+            helper.succeedIfManagerDidThingWithoutLagging(manager, () -> {
+                // Verify ore was moved from source to furnace input
+                assertTrue(
+                        count(oreHandler, Blocks.GOLD_ORE) == 0,
+                        "Ore chest should be empty but has " + count(oreHandler, Blocks.GOLD_ORE) + " gold ore"
+                );
+                assertTrue(
+                        count(furnaceHandler, Blocks.GOLD_ORE) == 32,
+                        "Furnace should have 32 gold ore in input slots but has " + count(furnaceHandler, Blocks.GOLD_ORE)
+                );
+
+                // Verify ingots were moved from furnace output to ingot chest
+                var ingotsHandler = helper.getItemHandler(ingotsPos);
+                assertTrue(
+                        count(ingotsHandler, Blocks.GOLD_BLOCK) == 4,
+                        "Ingot chest should have 4 gold blocks but has " + count(ingotsHandler, Blocks.GOLD_BLOCK)
+                );
+                assertTrue(
+                        count(furnaceHandler, Blocks.GOLD_BLOCK) == 0,
+                        "Furnace output should be empty but has " + count(furnaceHandler, Blocks.GOLD_BLOCK)
+                );
+            });
+        });
+    }
+}
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryProtocolConstraintValidationGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryProtocolConstraintValidationGameTest.java
new file mode 100644
index 000000000..039d749ea
--- /dev/null
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryProtocolConstraintValidationGameTest.java
@@ -0,0 +1,146 @@
+package ca.teamdman.sfm.gametest.tests.library;
+
+import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
+import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
+import ca.teamdman.sfm.common.item.DiskItem;
+import ca.teamdman.sfm.common.registry.SFMBlocks;
+import ca.teamdman.sfm.common.registry.SFMItems;
+import ca.teamdman.sfm.gametest.SFMGameTest;
+import ca.teamdman.sfm.gametest.SFMGameTestDefinition;
+import ca.teamdman.sfm.gametest.SFMGameTestHelper;
+import net.minecraft.core.BlockPos;
+import net.minecraft.world.item.ItemStack;
+
+import static ca.teamdman.sfm.gametest.SFMGameTestMethodHelpers.assertTrue;
+
+/**
+ * Tests that protocol constraints in macros are validated at compile time.
+ * <p>
+ * The library defines:
+ * - IOCapable protocol with input and output fields
+ * - ValidDevice struct that implements IOCapable
+ * - InvalidDevice struct that does NOT implement IOCapable
+ * - transfer macro with IOCapable constraint
+ * <p>
+ * Test verifies:
+ * 1. Using ValidDevice with the macro compiles successfully
+ * 2. Using InvalidDevice with the macro produces compile errors
+ */
+@SuppressWarnings({
+        "RedundantSuppression",
+        "DataFlowIssue",
+        "OptionalGetWithoutIsPresent",
+        "DuplicatedCode"
+})
+@SFMGameTest
+public class LibraryProtocolConstraintValidationGameTest extends SFMGameTestDefinition {
+
+    @Override
+    public String template() {
+        return "3x3x3";
+    }
+
+    @Override
+    public int maxTicks() {
+        return 100;
+    }
+
+    @Override
+    public void run(SFMGameTestHelper helper) {
+        // Layout (y=2 front row): [Library] - [Manager] - [empty]
+        // Layout (y=2 back row):  [cable]   - [cable]   - [empty]
+        BlockPos libraryPos = new BlockPos(0, 2, 0);
+        BlockPos managerPos = new BlockPos(1, 2, 0);
+
+        // Cable row behind to connect
+        BlockPos cable0Pos = new BlockPos(0, 2, 1);
+        BlockPos cable1Pos = new BlockPos(1, 2, 1);
+
+        // Place main blocks
+        helper.setBlock(libraryPos, SFMBlocks.LIBRARY_BLOCK.get());
+        helper.setBlock(managerPos, SFMBlocks.MANAGER_BLOCK.get());
+
+        // Place cable row behind
+        helper.setBlock(cable0Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable1Pos, SFMBlocks.CABLE_BLOCK.get());
+
+        // Get block entities
+        LibraryBlockEntity library = (LibraryBlockEntity) helper.getBlockEntity(libraryPos);
+        ManagerBlockEntity manager = (ManagerBlockEntity) helper.getBlockEntity(managerPos);
+
+        // Create library disk with protocol, valid struct, invalid struct, and macro
+        ItemStack libraryDisk = new ItemStack(SFMItems.DISK_ITEM.get());
+        DiskItem.setProgram(libraryDisk, """
+                NAME "constrained_lib"
+
+                protocol IOCapable
+                    input: sidequalifier slotqualifier
+                    output: sidequalifier slotqualifier
+                end
+
+                struct ValidDevice : IOCapable
+                    input: EACH SIDE SLOTS 0-8
+                    output: EACH SIDE SLOTS 9-17
+                end
+
+                struct InvalidDevice
+                    storage: SLOTS 0-26
+                end
+
+                macro transfer(device: IOCapable, src, dst)
+                    input from src
+                    output to device using input
+                end
+                """);
+        library.setItem(0, libraryDisk);
+
+        // Wait for library to compile
+        helper.runAfterDelay(10, () -> {
+            // Verify library disk has no errors
+            ItemStack compiledLibraryDisk = library.getItem(0);
+            assertTrue(
+                    DiskItem.getErrors(compiledLibraryDisk).isEmpty(),
+                    "Library disk should have no errors but had: " + DiskItem.getErrors(compiledLibraryDisk)
+            );
+
+            // Test 1: Valid usage - struct implements required protocol
+            manager.setItem(0, new ItemStack(SFMItems.DISK_ITEM.get()));
+            manager.setProgram("""
+                    NAME "Valid Usage"
+                    use library "constrained_lib"
+
+                    let device = ValidDevice { label: "devices" }
+                    every 20 ticks do
+                        DO transfer(device, a, b)
+                    end
+                    """);
+
+            helper.runAfterDelay(5, () -> {
+                assertTrue(
+                        DiskItem.getErrors(manager.getDisk()).isEmpty(),
+                        "Valid usage should have no errors but had: " + DiskItem.getErrors(manager.getDisk())
+                );
+
+                // Test 2: Invalid usage - struct doesn't implement required protocol
+                manager.setProgram("""
+                        NAME "Invalid Usage"
+                        use library "constrained_lib"
+
+                        let device = InvalidDevice { label: "devices" }
+                        every 20 ticks do
+                            DO transfer(device, a, b)
+                        end
+                        """);
+
+                helper.runAfterDelay(5, () -> {
+                    assertTrue(
+                            !DiskItem.getErrors(manager.getDisk()).isEmpty(),
+                            "Invalid usage should have compile errors for using struct that doesn't implement protocol"
+                    );
+
+                    helper.succeed();
+                });
+            });
+        });
+    }
+}
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithCombinedIOProtocolGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithCombinedIOProtocolGameTest.java
new file mode 100644
index 000000000..7badda076
--- /dev/null
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithCombinedIOProtocolGameTest.java
@@ -0,0 +1,178 @@
+package ca.teamdman.sfm.gametest.tests.library;
+
+import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
+import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
+import ca.teamdman.sfm.common.item.DiskItem;
+import ca.teamdman.sfm.common.label.LabelPositionHolder;
+import ca.teamdman.sfm.common.registry.SFMBlocks;
+import ca.teamdman.sfm.common.registry.SFMItems;
+import ca.teamdman.sfm.gametest.SFMGameTest;
+import ca.teamdman.sfm.gametest.SFMGameTestDefinition;
+import ca.teamdman.sfm.gametest.SFMGameTestHelper;
+import net.minecraft.core.BlockPos;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.block.Blocks;
+
+import static ca.teamdman.sfm.gametest.SFMGameTestCountHelpers.count;
+import static ca.teamdman.sfm.gametest.SFMGameTestMethodHelpers.assertTrue;
+
+/**
+ * Tests that a library with a combined I/O protocol (both input and output fields)
+ * can be imported and used with a macro that processes items through a machine.
+ * <p>
+ * The library defines:
+ * - Processable protocol with both input and output fields
+ * - Machine struct implementing Processable
+ * - process macro with Processable constraint
+ * <p>
+ * This tests the scenario where a single protocol contains both input and output
+ * definitions, and a macro uses both fields from the same struct parameter.
+ */
+@SuppressWarnings({
+        "RedundantSuppression",
+        "DataFlowIssue",
+        "OptionalGetWithoutIsPresent",
+        "DuplicatedCode"
+})
+@SFMGameTest
+public class LibraryWithCombinedIOProtocolGameTest extends SFMGameTestDefinition {
+
+    @Override
+    public String template() {
+        return "5x3x3";
+    }
+
+    @Override
+    public int maxTicks() {
+        return 200;
+    }
+
+    @Override
+    public void run(SFMGameTestHelper helper) {
+        // Layout (y=2 front row): [source] - [Library] - [Manager] - [machine] - [dest]
+        // Layout (y=2 back row):  [cable]  - [cable]   - [cable]   - [cable]   - [cable]
+        BlockPos sourcePos = new BlockPos(0, 2, 0);
+        BlockPos libraryPos = new BlockPos(1, 2, 0);
+        BlockPos managerPos = new BlockPos(2, 2, 0);
+        BlockPos machinePos = new BlockPos(3, 2, 0);
+        BlockPos destPos = new BlockPos(4, 2, 0);
+
+        // Cable row behind to connect everything
+        BlockPos cable0Pos = new BlockPos(0, 2, 1);
+        BlockPos cable1Pos = new BlockPos(1, 2, 1);
+        BlockPos cable2Pos = new BlockPos(2, 2, 1);
+        BlockPos cable3Pos = new BlockPos(3, 2, 1);
+        BlockPos cable4Pos = new BlockPos(4, 2, 1);
+
+        // Place main blocks
+        helper.setBlock(sourcePos, SFMBlocks.TEST_BARREL_BLOCK.get());
+        helper.setBlock(libraryPos, SFMBlocks.LIBRARY_BLOCK.get());
+        helper.setBlock(managerPos, SFMBlocks.MANAGER_BLOCK.get());
+        helper.setBlock(machinePos, SFMBlocks.TEST_BARREL_BLOCK.get());
+        helper.setBlock(destPos, SFMBlocks.TEST_BARREL_BLOCK.get());
+
+        // Place cable row behind
+        helper.setBlock(cable0Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable1Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable2Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable3Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable4Pos, SFMBlocks.CABLE_BLOCK.get());
+
+        // Get block entities
+        LibraryBlockEntity library = (LibraryBlockEntity) helper.getBlockEntity(libraryPos);
+        ManagerBlockEntity manager = (ManagerBlockEntity) helper.getBlockEntity(managerPos);
+
+        // Create library disk with combined protocol, struct, and macro
+        ItemStack libraryDisk = new ItemStack(SFMItems.DISK_ITEM.get());
+        DiskItem.setProgram(libraryDisk, """
+                NAME "combined_lib"
+
+                protocol Processable
+                    input: sidequalifier slotqualifier
+                    output: sidequalifier slotqualifier
+                end
+
+                struct Machine : Processable
+                    input: EACH SIDE SLOTS 0-8
+                    output: EACH SIDE SLOTS 9-17
+                end
+
+                macro process(device: Processable, src, dst)
+                    input from src
+                    output to device using input
+                    forget
+                    input from device using output
+                    output to dst
+                end
+                """);
+        library.setItem(0, libraryDisk);
+
+        // Create manager disk that imports the library
+        manager.setItem(0, new ItemStack(SFMItems.DISK_ITEM.get()));
+        manager.setProgram("""
+                NAME "Combined Manager"
+
+                use library "combined_lib"
+
+                let machine = Machine { label: "machine" }
+
+                every 20 ticks do
+                    DO process(machine, source, dest)
+                end
+                """);
+
+        // Setup labels
+        LabelPositionHolder labelHolder = LabelPositionHolder.empty()
+                .add("source", helper.absolutePos(sourcePos))
+                .add("machine", helper.absolutePos(machinePos))
+                .add("dest", helper.absolutePos(destPos));
+        labelHolder.save(manager.getDisk());
+
+        // Put items in source
+        var sourceHandler = helper.getItemHandler(sourcePos);
+        sourceHandler.insertItem(0, new ItemStack(Blocks.COAL_ORE, 32), false);
+
+        // Put processed items in machine's output slots
+        var machineHandler = helper.getItemHandler(machinePos);
+        machineHandler.insertItem(9, new ItemStack(Blocks.COAL_BLOCK, 4), false);
+
+        // Wait for the library to compile and manager to run
+        helper.runAfterDelay(10, () -> {
+            // Verify library disk has no errors
+            ItemStack compiledLibraryDisk = library.getItem(0);
+            assertTrue(
+                    DiskItem.getErrors(compiledLibraryDisk).isEmpty(),
+                    "Library disk should have no errors but had: " + DiskItem.getErrors(compiledLibraryDisk)
+            );
+
+            // Verify manager disk has no errors
+            assertTrue(
+                    DiskItem.getErrors(manager.getDisk()).isEmpty(),
+                    "Manager disk should have no errors but had: " + DiskItem.getErrors(manager.getDisk())
+            );
+
+            helper.succeedIfManagerDidThingWithoutLagging(manager, () -> {
+                // Verify items were moved from source to machine's input slots
+                assertTrue(
+                        count(sourceHandler, Blocks.COAL_ORE) == 0,
+                        "Source should be empty but has " + count(sourceHandler, Blocks.COAL_ORE) + " coal ore"
+                );
+                assertTrue(
+                        count(machineHandler, Blocks.COAL_ORE) == 32,
+                        "Machine should have 32 coal ore in input slots but has " + count(machineHandler, Blocks.COAL_ORE)
+                );
+
+                // Verify items were moved from machine's output slots to dest
+                var destHandler = helper.getItemHandler(destPos);
+                assertTrue(
+                        count(destHandler, Blocks.COAL_BLOCK) == 4,
+                        "Dest should have 4 coal blocks but has " + count(destHandler, Blocks.COAL_BLOCK)
+                );
+                assertTrue(
+                        count(machineHandler, Blocks.COAL_BLOCK) == 0,
+                        "Machine output slots should be empty but has " + count(machineHandler, Blocks.COAL_BLOCK)
+                );
+            });
+        });
+    }
+}
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithStructIOProtocolsGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithStructIOProtocolsGameTest.java
new file mode 100644
index 000000000..cdbd84284
--- /dev/null
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithStructIOProtocolsGameTest.java
@@ -0,0 +1,176 @@
+package ca.teamdman.sfm.gametest.tests.library;
+
+import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
+import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
+import ca.teamdman.sfm.common.item.DiskItem;
+import ca.teamdman.sfm.common.label.LabelPositionHolder;
+import ca.teamdman.sfm.common.registry.SFMBlocks;
+import ca.teamdman.sfm.common.registry.SFMItems;
+import ca.teamdman.sfm.gametest.SFMGameTest;
+import ca.teamdman.sfm.gametest.SFMGameTestDefinition;
+import ca.teamdman.sfm.gametest.SFMGameTestHelper;
+import net.minecraft.core.BlockPos;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.block.Blocks;
+
+import static ca.teamdman.sfm.gametest.SFMGameTestCountHelpers.count;
+import static ca.teamdman.sfm.gametest.SFMGameTestMethodHelpers.assertTrue;
+
+/**
+ * Tests that a library with a struct implementing input/output protocols
+ * can be imported and used by a manager program at runtime.
+ * <p>
+ * The library defines:
+ * - HasInput protocol with input field
+ * - HasOutput protocol with output field
+ * - IODevice struct implementing both protocols
+ * <p>
+ * The manager imports the library, creates an IODevice instance,
+ * and uses it for item transfer via the struct's input/output fields.
+ */
+@SuppressWarnings({
+        "RedundantSuppression",
+        "DataFlowIssue",
+        "OptionalGetWithoutIsPresent",
+        "DuplicatedCode"
+})
+@SFMGameTest
+public class LibraryWithStructIOProtocolsGameTest extends SFMGameTestDefinition {
+
+    @Override
+    public String template() {
+        return "5x3x3";
+    }
+
+    @Override
+    public int maxTicks() {
+        return 200;
+    }
+
+    @Override
+    public void run(SFMGameTestHelper helper) {
+        // Layout (y=2 front row): [source] - [Library] - [Manager] - [device] - [dest]
+        // Layout (y=2 back row):  [cable]  - [cable]   - [cable]   - [cable]  - [cable]
+        BlockPos sourcePos = new BlockPos(0, 2, 0);
+        BlockPos libraryPos = new BlockPos(1, 2, 0);
+        BlockPos managerPos = new BlockPos(2, 2, 0);
+        BlockPos devicePos = new BlockPos(3, 2, 0);
+        BlockPos destPos = new BlockPos(4, 2, 0);
+
+        // Cable row behind to connect everything
+        BlockPos cable0Pos = new BlockPos(0, 2, 1);
+        BlockPos cable1Pos = new BlockPos(1, 2, 1);
+        BlockPos cable2Pos = new BlockPos(2, 2, 1);
+        BlockPos cable3Pos = new BlockPos(3, 2, 1);
+        BlockPos cable4Pos = new BlockPos(4, 2, 1);
+
+        // Place main blocks
+        helper.setBlock(sourcePos, SFMBlocks.TEST_BARREL_BLOCK.get());
+        helper.setBlock(libraryPos, SFMBlocks.LIBRARY_BLOCK.get());
+        helper.setBlock(managerPos, SFMBlocks.MANAGER_BLOCK.get());
+        helper.setBlock(devicePos, SFMBlocks.TEST_BARREL_BLOCK.get());
+        helper.setBlock(destPos, SFMBlocks.TEST_BARREL_BLOCK.get());
+
+        // Place cable row behind
+        helper.setBlock(cable0Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable1Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable2Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable3Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable4Pos, SFMBlocks.CABLE_BLOCK.get());
+
+        // Get block entities
+        LibraryBlockEntity library = (LibraryBlockEntity) helper.getBlockEntity(libraryPos);
+        ManagerBlockEntity manager = (ManagerBlockEntity) helper.getBlockEntity(managerPos);
+
+        // Create library disk with protocols and struct
+        ItemStack libraryDisk = new ItemStack(SFMItems.DISK_ITEM.get());
+        DiskItem.setProgram(libraryDisk, """
+                NAME "io_lib"
+
+                protocol HasInput
+                    input: sidequalifier slotqualifier
+                end
+
+                protocol HasOutput
+                    output: sidequalifier slotqualifier
+                end
+
+                struct IODevice : HasInput, HasOutput
+                    input: EACH SIDE SLOTS 0-8
+                    output: EACH SIDE SLOTS 9-17
+                end
+                """);
+        library.setItem(0, libraryDisk);
+
+        // Create manager disk that imports the library
+        manager.setItem(0, new ItemStack(SFMItems.DISK_ITEM.get()));
+        manager.setProgram("""
+                NAME "IO Manager"
+
+                use library "io_lib"
+
+                let device = IODevice { label: "device" }
+
+                every 20 ticks do
+                    -- Move items from source to device's input slots
+                    input from source_chest
+                    output to device using input
+                    forget
+
+                    -- Move items from device's output slots to dest
+                    input from device using output
+                    output to dest_chest
+                end
+                """);
+
+        // Setup labels
+        LabelPositionHolder labelHolder = LabelPositionHolder.empty()
+                .add("source_chest", helper.absolutePos(sourcePos))
+                .add("device", helper.absolutePos(devicePos))
+                .add("dest_chest", helper.absolutePos(destPos));
+        labelHolder.save(manager.getDisk());
+
+        // Put items in source chest
+        var sourceHandler = helper.getItemHandler(sourcePos);
+        sourceHandler.insertItem(0, new ItemStack(Blocks.DIRT, 32), false);
+
+        // Put items in device's output slots (slots 9-17) to be moved to dest
+        var deviceHandler = helper.getItemHandler(devicePos);
+        deviceHandler.insertItem(9, new ItemStack(Blocks.STONE, 16), false);
+
+        // Wait for the library to compile and manager to run
+        helper.runAfterDelay(10, () -> {
+            // Verify library disk has no errors
+            ItemStack compiledLibraryDisk = library.getItem(0);
+            assertTrue(
+                    DiskItem.getErrors(compiledLibraryDisk).isEmpty(),
+                    "Library disk should have no errors but had: " + DiskItem.getErrors(compiledLibraryDisk)
+            );
+
+            // Verify manager disk has no errors
+            assertTrue(
+                    DiskItem.getErrors(manager.getDisk()).isEmpty(),
+                    "Manager disk should have no errors but had: " + DiskItem.getErrors(manager.getDisk())
+            );
+
+            helper.succeedIfManagerDidThingWithoutLagging(manager, () -> {
+                // Verify items were moved from source to device's input slots
+                assertTrue(
+                        count(sourceHandler, Blocks.DIRT) == 0,
+                        "Source should be empty but has " + count(sourceHandler, Blocks.DIRT) + " dirt"
+                );
+                assertTrue(
+                        count(deviceHandler, Blocks.DIRT) == 32,
+                        "Device should have 32 dirt in input slots but has " + count(deviceHandler, Blocks.DIRT)
+                );
+
+                // Verify items were moved from device's output slots to dest
+                var destHandler = helper.getItemHandler(destPos);
+                assertTrue(
+                        count(destHandler, Blocks.STONE) == 16,
+                        "Dest should have 16 stone but has " + count(destHandler, Blocks.STONE)
+                );
+            });
+        });
+    }
+}
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithTransferMacroGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithTransferMacroGameTest.java
new file mode 100644
index 000000000..4c725e5e6
--- /dev/null
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithTransferMacroGameTest.java
@@ -0,0 +1,181 @@
+package ca.teamdman.sfm.gametest.tests.library;
+
+import ca.teamdman.sfm.common.blockentity.LibraryBlockEntity;
+import ca.teamdman.sfm.common.blockentity.ManagerBlockEntity;
+import ca.teamdman.sfm.common.item.DiskItem;
+import ca.teamdman.sfm.common.label.LabelPositionHolder;
+import ca.teamdman.sfm.common.registry.SFMBlocks;
+import ca.teamdman.sfm.common.registry.SFMItems;
+import ca.teamdman.sfm.gametest.SFMGameTest;
+import ca.teamdman.sfm.gametest.SFMGameTestDefinition;
+import ca.teamdman.sfm.gametest.SFMGameTestHelper;
+import net.minecraft.core.BlockPos;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.block.Blocks;
+
+import static ca.teamdman.sfm.gametest.SFMGameTestCountHelpers.count;
+import static ca.teamdman.sfm.gametest.SFMGameTestMethodHelpers.assertTrue;
+
+/**
+ * Tests that a library with a macro using protocol constraints
+ * can be imported and executed by a manager program at runtime.
+ * <p>
+ * The library defines:
+ * - HasInput and HasOutput protocols
+ * - Processor struct implementing both protocols
+ * - transfer_through macro with protocol-constrained parameters
+ * <p>
+ * The manager imports the library and uses the macro to transfer items
+ * through a processor device (input -> processor.input -> processor.output -> output).
+ */
+@SuppressWarnings({
+        "RedundantSuppression",
+        "DataFlowIssue",
+        "OptionalGetWithoutIsPresent",
+        "DuplicatedCode"
+})
+@SFMGameTest
+public class LibraryWithTransferMacroGameTest extends SFMGameTestDefinition {
+
+    @Override
+    public String template() {
+        return "5x3x3";
+    }
+
+    @Override
+    public int maxTicks() {
+        return 200;
+    }
+
+    @Override
+    public void run(SFMGameTestHelper helper) {
+        // Layout (y=2 front row): [input] - [Library] - [Manager] - [processor] - [output]
+        // Layout (y=2 back row):  [cable] - [cable]   - [cable]   - [cable]     - [cable]
+        BlockPos inputPos = new BlockPos(0, 2, 0);
+        BlockPos libraryPos = new BlockPos(1, 2, 0);
+        BlockPos managerPos = new BlockPos(2, 2, 0);
+        BlockPos processorPos = new BlockPos(3, 2, 0);
+        BlockPos outputPos = new BlockPos(4, 2, 0);
+
+        // Cable row behind to connect everything
+        BlockPos cable0Pos = new BlockPos(0, 2, 1);
+        BlockPos cable1Pos = new BlockPos(1, 2, 1);
+        BlockPos cable2Pos = new BlockPos(2, 2, 1);
+        BlockPos cable3Pos = new BlockPos(3, 2, 1);
+        BlockPos cable4Pos = new BlockPos(4, 2, 1);
+
+        // Place main blocks
+        helper.setBlock(inputPos, SFMBlocks.TEST_BARREL_BLOCK.get());
+        helper.setBlock(libraryPos, SFMBlocks.LIBRARY_BLOCK.get());
+        helper.setBlock(managerPos, SFMBlocks.MANAGER_BLOCK.get());
+        helper.setBlock(processorPos, SFMBlocks.TEST_BARREL_BLOCK.get());
+        helper.setBlock(outputPos, SFMBlocks.TEST_BARREL_BLOCK.get());
+
+        // Place cable row behind
+        helper.setBlock(cable0Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable1Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable2Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable3Pos, SFMBlocks.CABLE_BLOCK.get());
+        helper.setBlock(cable4Pos, SFMBlocks.CABLE_BLOCK.get());
+
+        // Get block entities
+        LibraryBlockEntity library = (LibraryBlockEntity) helper.getBlockEntity(libraryPos);
+        ManagerBlockEntity manager = (ManagerBlockEntity) helper.getBlockEntity(managerPos);
+
+        // Create library disk with protocols, struct, and macro
+        ItemStack libraryDisk = new ItemStack(SFMItems.DISK_ITEM.get());
+        DiskItem.setProgram(libraryDisk, """
+                NAME "transfer_lib"
+
+                protocol HasInput
+                    input: sidequalifier slotqualifier
+                end
+
+                protocol HasOutput
+                    output: sidequalifier slotqualifier
+                end
+
+                struct Processor : HasInput, HasOutput
+                    input: EACH SIDE SLOTS 0-8
+                    output: EACH SIDE SLOTS 9-17
+                end
+
+                macro transfer_through(machine: HasInput, machine2: HasOutput, src, dst)
+                    input from src
+                    output to machine using input
+                    forget
+                    input from machine2 using output
+                    output to dst
+                end
+                """);
+        library.setItem(0, libraryDisk);
+
+        // Create manager disk that imports the library and uses the macro
+        manager.setItem(0, new ItemStack(SFMItems.DISK_ITEM.get()));
+        manager.setProgram("""
+                NAME "Transfer Manager"
+
+                use library "transfer_lib"
+
+                let processor = Processor { label: "processor" }
+
+                every 20 ticks do
+                    DO transfer_through(processor, processor, input_chest, output_chest)
+                end
+                """);
+
+        // Setup labels
+        LabelPositionHolder labelHolder = LabelPositionHolder.empty()
+                .add("input_chest", helper.absolutePos(inputPos))
+                .add("processor", helper.absolutePos(processorPos))
+                .add("output_chest", helper.absolutePos(outputPos));
+        labelHolder.save(manager.getDisk());
+
+        // Put items in input chest
+        var inputHandler = helper.getItemHandler(inputPos);
+        inputHandler.insertItem(0, new ItemStack(Blocks.IRON_ORE, 64), false);
+
+        // Simulate processed items in processor's output slots
+        var processorHandler = helper.getItemHandler(processorPos);
+        processorHandler.insertItem(9, new ItemStack(Blocks.IRON_BLOCK, 8), false);
+
+        // Wait for the library to compile and manager to run
+        helper.runAfterDelay(10, () -> {
+            // Verify library disk has no errors
+            ItemStack compiledLibraryDisk = library.getItem(0);
+            assertTrue(
+                    DiskItem.getErrors(compiledLibraryDisk).isEmpty(),
+                    "Library disk should have no errors but had: " + DiskItem.getErrors(compiledLibraryDisk)
+            );
+
+            // Verify manager disk has no errors
+            assertTrue(
+                    DiskItem.getErrors(manager.getDisk()).isEmpty(),
+                    "Manager disk should have no errors but had: " + DiskItem.getErrors(manager.getDisk())
+            );
+
+            helper.succeedIfManagerDidThingWithoutLagging(manager, () -> {
+                // Verify items were moved from input to processor's input slots
+                assertTrue(
+                        count(inputHandler, Blocks.IRON_ORE) == 0,
+                        "Input should be empty but has " + count(inputHandler, Blocks.IRON_ORE) + " iron ore"
+                );
+                assertTrue(
+                        count(processorHandler, Blocks.IRON_ORE) == 64,
+                        "Processor should have 64 iron ore in input slots but has " + count(processorHandler, Blocks.IRON_ORE)
+                );
+
+                // Verify items were moved from processor's output slots to output
+                var outputHandler = helper.getItemHandler(outputPos);
+                assertTrue(
+                        count(outputHandler, Blocks.IRON_BLOCK) == 8,
+                        "Output should have 8 iron blocks but has " + count(outputHandler, Blocks.IRON_BLOCK)
+                );
+                assertTrue(
+                        count(processorHandler, Blocks.IRON_BLOCK) == 0,
+                        "Processor output slots should be empty but has " + count(processorHandler, Blocks.IRON_BLOCK)
+                );
+            });
+        });
+    }
+}
diff --git a/src/test/java/ca/teamdman/sfml/SFMLTestHelpers.java b/src/test/java/ca/teamdman/sfml/SFMLTestHelpers.java
index a39f60321..2117e789f 100644
--- a/src/test/java/ca/teamdman/sfml/SFMLTestHelpers.java
+++ b/src/test/java/ca/teamdman/sfml/SFMLTestHelpers.java
@@ -4,16 +4,19 @@
 import ca.teamdman.langs.SFMLParser;
 import ca.teamdman.sfml.ast.ASTBuilder;
 import ca.teamdman.sfml.ast.Program;
+import ca.teamdman.sfml.program_builder.LibraryDefinitions;
+import ca.teamdman.sfml.program_builder.LibraryResolver;
+import ca.teamdman.sfml.program_builder.ProgramBuilder;
 import org.antlr.v4.runtime.CharStreams;
 import org.antlr.v4.runtime.CommonTokenStream;
 
 import java.io.PrintWriter;
 import java.io.StringWriter;
-import java.util.ArrayList;
-import java.util.List;
+import java.util.*;
+
+import static org.junit.jupiter.api.Assertions.*;
+
 
-import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertNotEquals;
 
 public class SFMLTestHelpers {
     public static CompileErrors getCompileErrors(String input) {
@@ -91,6 +94,87 @@ public static Program compile(String input) {
         return builder.visitProgram(context);
     }
 
+    /**
+     * Creates a mock LibraryResolver from a map of library names to source code.
+     */
+    public static LibraryResolver createMockLibraryResolver(Map<String, String> libraries) {
+        return createMockLibraryResolver(libraries, new HashSet<>());
+    }
+
+    private static LibraryResolver createMockLibraryResolver(
+            Map<String, String> libraries,
+            Set<String> beingResolved
+    ) {
+        return libraryName -> {
+            String source = libraries.get(libraryName);
+            if (source == null) return Optional.empty();
+
+            if (beingResolved.contains(libraryName)) {
+                throw new IllegalArgumentException("Circular library dependency detected: " + libraryName);
+            }
+
+            beingResolved.add(libraryName);
+            try {
+                LibraryResolver nestedResolver = createMockLibraryResolver(libraries, beingResolved);
+                return Optional.of(parseLibraryDefinitions(source, nestedResolver));
+            } finally {
+                beingResolved.remove(libraryName);
+            }
+        };
+    }
+
+    /**
+     * Parses library definitions from source code.
+     */
+    public static LibraryDefinitions parseLibraryDefinitions(String source, LibraryResolver resolver) {
+        var buildResult = new ProgramBuilder(source)
+                .withLibraryResolver(resolver)
+                .useCache(false)
+                .build();
+
+        if (!buildResult.metadata().errors().isEmpty()) {
+            throw new IllegalArgumentException("Library has compile errors: " + buildResult.metadata().errors());
+        }
+
+        Program program = buildResult.program();
+        return new LibraryDefinitions(
+                program.protocolDefinitions(),
+                program.structDefinitions(),
+                program.macroDefinitions()
+        );
+    }
+
+    /**
+     * Asserts no compile errors with library resolution.
+     */
+    public static void assertNoCompileErrorsWithLibraries(String program, Map<String, String> libraries) {
+        LibraryResolver resolver = createMockLibraryResolver(libraries);
+        var buildResult = new ProgramBuilder(program)
+                .withLibraryResolver(resolver)
+                .useCache(false)
+                .build();
+
+        if (!buildResult.metadata().errors().isEmpty()) {
+            fail("Expected no compile errors but got: " + buildResult.metadata().errors());
+        }
+    }
+
+    /**
+     * Compiles a program with library resolution.
+     */
+    public static Program compileWithLibraries(String input, Map<String, String> libraries) {
+        LibraryResolver resolver = createMockLibraryResolver(libraries);
+        var buildResult = new ProgramBuilder(input)
+                .withLibraryResolver(resolver)
+                .useCache(false)
+                .build();
+
+        if (!buildResult.metadata().errors().isEmpty()) {
+            throw new RuntimeException("Compilation failed: " + buildResult.metadata().errors());
+        }
+        return buildResult.program();
+    }
+
     public record CompileErrors(
             List<String> lexerErrors,
             List<String> parserErrors,
diff --git a/src/test/java/ca/teamdman/sfml/SFMLTests.java b/src/test/java/ca/teamdman/sfml/SFMLTests.java
index bd1e9f941..eaed480f3 100644
--- a/src/test/java/ca/teamdman/sfml/SFMLTests.java
+++ b/src/test/java/ca/teamdman/sfml/SFMLTests.java
@@ -21,6 +21,7 @@
 import java.nio.file.Files;
 import java.nio.file.Paths;
 import java.util.Arrays;
+import java.util.Map;
 import java.util.stream.Collectors;
 
 import static ca.teamdman.sfml.SFMLTestHelpers.*;
@@ -1434,6 +1435,289 @@ public void multipleLibraries() {
         );
     }
 
+    @Test
+    public void libraryWithInputOutputProtocolStruct() {
+        String librarySource = """
+            NAME "io_lib"
+
+            protocol HasInput
+                input: sidequalifier slotqualifier
+            end
+
+            protocol HasOutput
+                output: sidequalifier slotqualifier
+            end
+
+            struct IODevice : HasInput, HasOutput
+                input: TOP SIDE SLOTS 0
+                output: BOTTOM SIDE SLOTS 1
+            end
+            """;
+
+        Map<String, String> libraries = Map.of("io_lib", librarySource);
+
+        String managerProgram = """
+            NAME "IO Manager"
+
+            use library "io_lib"
+
+            let device = IODevice { label: "devices" }
+
+            every 20 ticks do
+                input from source_chest
+                output to device using input
+                forget
+                input from device using output
+                output to dest_chest
+            end
+            """;
+
+        assertNoCompileErrorsWithLibraries(managerProgram, libraries);
+    }
+
+    @Test
+    public void libraryWithTransferMacro() {
+        String librarySource = """
+            NAME "transfer_lib"
+
+            protocol HasInput
+                input: sidequalifier slotqualifier
+            end
+
+            protocol HasOutput
+                output: sidequalifier slotqualifier
+            end
+
+            struct Processor : HasInput, HasOutput
+                input: TOP SIDE SLOTS 0
+                output: BOTTOM SIDE SLOTS 1
+            end
+
+            macro transfer_through(machine: HasInput, machine2: HasOutput, src, dst)
+                input from src
+                output to machine using input
+                forget
+                input from machine2 using output
+                output to dst
+            end
+            """;
+
+        Map<String, String> libraries = Map.of("transfer_lib", librarySource);
+
+        String managerProgram = """
+            NAME "Transfer Manager"
+
+            use library "transfer_lib"
+
+            let processor = Processor { label: "processors" }
+
+            every 20 ticks do
+                DO transfer_through(processor, processor, input_chest, output_chest)
+            end
+            """;
+
+        assertNoCompileErrorsWithLibraries(managerProgram, libraries);
+
+        var program = compileWithLibraries(managerProgram, libraries);
+
+        // Verify the program structure
+        assertEquals(1, program.triggers().size());
+        assertEquals(1, program.letStatements().size());
+
+        // Verify macro expansion
+        var trigger = program.triggers().get(0);
+        var statements = trigger.getBlock().getStatements();
+        assertEquals(1, statements.size());
+        assertTrue(statements.get(0) instanceof ca.teamdman.sfml.ast.ExpandStatement);
+    }
+
+    @Test
+    public void libraryWithCombinedIOProtocolAndMacro() {
+        String librarySource = """
+            NAME "combined_lib"
+
+            protocol Processable
+                input: sidequalifier slotqualifier
+                output: sidequalifier slotqualifier
+            end
+
+            struct Machine : Processable
+                input: TOP SIDE SLOTS 0
+                output: BOTTOM SIDE SLOTS 1
+            end
+
+            macro process(device: Processable, src, dst)
+                input from src
+                output to device using input
+                forget
+                input from device using output
+                output to dst
+            end
+            """;
+
+        Map<String, String> libraries = Map.of("combined_lib", librarySource);
+
+        String managerProgram = """
+            NAME "Combined Manager"
+
+            use library "combined_lib"
+
+            let machine = Machine { label: "machines" }
+
+            every 20 ticks do
+                DO process(machine, source, dest)
+            end
+            """;
+
+        assertNoCompileErrorsWithLibraries(managerProgram, libraries);
+
+        var program = compileWithLibraries(managerProgram, libraries);
+
+        // Verify the program structure - library definitions are used for validation
+        // but only local definitions appear in the program's lists
+        assertEquals(1, program.triggers().size());
+        assertEquals(1, program.letStatements().size());
+
+        // Verify the let statement references the imported struct correctly
+        assertEquals("machine", program.letStatements().get(0).variableName());
+        assertEquals("Machine", program.letStatements().get(0).instance().definition().name());
+
+        // Verify the struct implements the protocol (from the struct definition)
+        var struct = program.letStatements().get(0).instance().definition();
+        assertTrue(struct.implementsProtocol("Processable"));
+    }
+
+    @Test
+    public void libraryMacroProtocolConstraintValidation() {
+        String librarySource = """
+            NAME "constrained_lib"
+
+            protocol IOCapable
+                input: sidequalifier slotqualifier
+                output: sidequalifier slotqualifier
+            end
+
+            struct ValidDevice : IOCapable
+                input: TOP SIDE SLOTS 0
+                output: BOTTOM SIDE SLOTS 1
+            end
+
+            struct InvalidDevice
+                storage: SLOTS 0-26
+            end
+
+            macro transfer(device: IOCapable, src, dst)
+                input from src
+                output to device using input
+            end
+            """;
+
+        Map<String, String> libraries = Map.of("constrained_lib", librarySource);
+
+        // Valid usage
+        String validProgram = """
+            NAME "Valid Usage"
+            use library "constrained_lib"
+
+            let device = ValidDevice { label: "devices" }
+            every 20 ticks do
+                DO transfer(device, a, b)
+            end
+            """;
+        assertNoCompileErrorsWithLibraries(validProgram, libraries);
+
+        // Invalid usage - struct doesn't implement required protocol
+        String invalidProgram = """
+            NAME "Invalid Usage"
+            use library "constrained_lib"
+
+            let device = InvalidDevice { label: "devices" }
+            every 20 ticks do
+                DO transfer(device, a, b)
+            end
+            """;
+
+        assertThrows(RuntimeException.class, () -> {
+            compileWithLibraries(invalidProgram, libraries);
+        });
+    }
+
+    @Test
+    public void chainedLibraryImports() {
+        // Libraries must explicitly import their dependencies - transitive imports
+        // make definitions available for validation but don't re-export them.
+        String baseLib = """
+            NAME "base_protocols"
+
+            protocol HasInput
+                input: sidequalifier slotqualifier
+            end
+
+            protocol HasOutput
+                output: sidequalifier slotqualifier
+            end
+            """;
+
+        String structLib = """
+            NAME "struct_lib"
+            use library "base_protocols"
+
+            struct Furnace : HasInput, HasOutput
+                input: TOP SIDE SLOTS 0
+                output: BOTTOM SIDE SLOTS 2
+            end
+            """;
+
+        // macro_lib needs to import both base_protocols (for protocol constraints)
+        // and struct_lib (for the Furnace struct)
+        String macroLib = """
+            NAME "macro_lib"
+            use library "base_protocols"
+            use library "struct_lib"
+
+            macro smelt(machine: HasInput, machine2: HasOutput, src, dst)
+                input from src
+                output to machine using input
+                forget
+                input from machine2 using output
+                output to dst
+            end
+            """;
+
+        Map<String, String> libraries = Map.of(
+            "base_protocols", baseLib,
+            "struct_lib", structLib,
+            "macro_lib", macroLib
+        );
+
+        // The manager also needs to import all required definitions
+        String managerProgram = """
+            NAME "Chained Manager"
+            use library "base_protocols"
+            use library "struct_lib"
+            use library "macro_lib"
+
+            let furnace = Furnace { label: "furnaces" }
+            every 20 ticks do
+                DO smelt(furnace, furnace, ore_chest, ingot_chest)
+            end
+            """;
+
+        assertNoCompileErrorsWithLibraries(managerProgram, libraries);
+
+        var program = compileWithLibraries(managerProgram, libraries);
+
+        // Verify the program structure
+        assertEquals(1, program.triggers().size());
+        assertEquals(1, program.letStatements().size());
+
+        // Verify the struct from the library chain is accessible
+        var instance = program.letStatements().get(0).instance();
+        assertEquals("Furnace", instance.definition().name());
+        assertTrue(instance.definition().implementsProtocol("HasInput"));
+        assertTrue(instance.definition().implementsProtocol("HasOutput"));
+    }
+
     // ===== COMBINED FEATURE TESTS =====
 
     @Test

From 39dd82281196822f06eccdeba6e331bdf1120aa8 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Mon, 26 Jan 2026 00:30:06 +0100
Subject: [PATCH 31/33] refactor: simplify struct instantiation syntax

---
 .../LibraryChainedImportsGameTest.java        |  3 +-
 ...yProtocolConstraintValidationGameTest.java |  6 +-
 ...LibraryWithCombinedIOProtocolGameTest.java |  2 +-
 .../LibraryWithStructIOProtocolsGameTest.java |  2 +-
 .../LibraryWithTransferMacroGameTest.java     |  2 +-
 .../struct/MacroWithStructAccessGameTest.java |  4 +-
 src/main/antlr/sfml/SFML.g4                   |  6 +-
 .../java/ca/teamdman/sfml/ast/ASTBuilder.java | 41 +++------
 .../ca/teamdman/sfml/ast/LetStatement.java    |  4 +-
 .../ca/teamdman/sfml/ast/StructInstance.java  | 26 ++++--
 .../sfm/template_programs/library_blocks.sfml |  4 +-
 .../protocols_and_macros.sfml                 |  9 +-
 .../assets/sfm/template_programs/structs.sfml | 10 +--
 src/test/java/ca/teamdman/sfml/SFMLTests.java | 86 ++++++++-----------
 .../syntaxes/SFML.g4                          |  6 +-
 15 files changed, 95 insertions(+), 116 deletions(-)

diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryChainedImportsGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryChainedImportsGameTest.java
index 25e734ae3..2a71cf97a 100644
--- a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryChainedImportsGameTest.java
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryChainedImportsGameTest.java
@@ -147,7 +147,8 @@ macro smelt(machine: HasInput, machine2: HasOutput, src, dst)
                 use library "struct_lib"
                 use library "macro_lib"
 
-                let furnace = Furnace { label: "furnace" }
+                let furnace = Furnace
+
                 every 20 ticks do
                     DO smelt(furnace, furnace, ore_chest, ingot_chest)
                 end
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryProtocolConstraintValidationGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryProtocolConstraintValidationGameTest.java
index 039d749ea..f908c06c4 100644
--- a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryProtocolConstraintValidationGameTest.java
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryProtocolConstraintValidationGameTest.java
@@ -109,7 +109,8 @@ macro transfer(device: IOCapable, src, dst)
                     NAME "Valid Usage"
                     use library "constrained_lib"
 
-                    let device = ValidDevice { label: "devices" }
+                    let device = ValidDevice
+
                     every 20 ticks do
                         DO transfer(device, a, b)
                     end
@@ -126,7 +127,8 @@ DO transfer(device, a, b)
                         NAME "Invalid Usage"
                         use library "constrained_lib"
 
-                        let device = InvalidDevice { label: "devices" }
+                        let device = InvalidDevice
+
                         every 20 ticks do
                             DO transfer(device, a, b)
                         end
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithCombinedIOProtocolGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithCombinedIOProtocolGameTest.java
index 7badda076..2f330fa93 100644
--- a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithCombinedIOProtocolGameTest.java
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithCombinedIOProtocolGameTest.java
@@ -114,7 +114,7 @@ macro process(device: Processable, src, dst)
 
                 use library "combined_lib"
 
-                let machine = Machine { label: "machine" }
+                let machine = Machine
 
                 every 20 ticks do
                     DO process(machine, source, dest)
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithStructIOProtocolsGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithStructIOProtocolsGameTest.java
index cdbd84284..a8db4a57b 100644
--- a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithStructIOProtocolsGameTest.java
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithStructIOProtocolsGameTest.java
@@ -109,7 +109,7 @@ public void run(SFMGameTestHelper helper) {
 
                 use library "io_lib"
 
-                let device = IODevice { label: "device" }
+                let device = IODevice
 
                 every 20 ticks do
                     -- Move items from source to device's input slots
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithTransferMacroGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithTransferMacroGameTest.java
index 4c725e5e6..0b1516caf 100644
--- a/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithTransferMacroGameTest.java
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/library/LibraryWithTransferMacroGameTest.java
@@ -117,7 +117,7 @@ macro transfer_through(machine: HasInput, machine2: HasOutput, src, dst)
 
                 use library "transfer_lib"
 
-                let processor = Processor { label: "processor" }
+                let processor = Processor
 
                 every 20 ticks do
                     DO transfer_through(processor, processor, input_chest, output_chest)
diff --git a/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroWithStructAccessGameTest.java b/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroWithStructAccessGameTest.java
index 12aea8532..ef026e0cc 100644
--- a/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroWithStructAccessGameTest.java
+++ b/src/gametest/java/ca/teamdman/sfm/gametest/tests/struct/MacroWithStructAccessGameTest.java
@@ -44,10 +44,10 @@ macro process(machine: Container, source, dest)
                     output to dest
                 end
 
-                let storage = Chest { label: "left" }
+                let left = Chest
 
                 every 20 ticks do
-                    do process(storage, left, right)
+                    do process(left, left, right)
                 end
                 """);
         test.preContents("left", Arrays.asList(
diff --git a/src/main/antlr/sfml/SFML.g4 b/src/main/antlr/sfml/SFML.g4
index e27f88d05..b6d0854aa 100644
--- a/src/main/antlr/sfml/SFML.g4
+++ b/src/main/antlr/sfml/SFML.g4
@@ -68,8 +68,8 @@ macroLabelAccess : identifier                                               #Mac
                  ;
 
 letStatement : LET identifier EQ_SYMBOL structInstantiation ;
-structInstantiation : identifier LBRACE structFieldAssignment (COMMA structFieldAssignment)* COMMA? RBRACE ;
-structFieldAssignment : identifier COLON structFieldValue ;
+structInstantiation : identifier (WITH structFieldOverride (COMMA structFieldOverride)*)? ;
+structFieldOverride : identifier COLON structFieldValue ;
 
 //
 // TRIGGERS
@@ -324,8 +324,6 @@ NAME            : N A M E ;
 STRUCT          : S T R U C T ;
 LET             : L E T ;
 USING           : U S I N G ;
-LBRACE          : '{' ;
-RBRACE          : '}' ;
 
 // PROTOCOL SYMBOLS
 PROTOCOL        : P R O T O C O L ;
diff --git a/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java b/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
index 6e38558b7..5e9917b08 100644
--- a/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
+++ b/src/main/java/ca/teamdman/sfml/ast/ASTBuilder.java
@@ -558,34 +558,27 @@ public StructInstance visitStructInstantiation(SFMLParser.StructInstantiationCon
             throw new IllegalArgumentException("Unknown struct: " + structName);
         }
 
-        // Process field assignments
+        // Use the variable name as the label automatically
+        Label label = new Label(variableName);
+        USED_LABELS.add(label);
+
+        // Create overrides map with the label
         Map<String, StructFieldValue> overrides = new LinkedHashMap<>();
-        for (SFMLParser.StructFieldAssignmentContext assignCtx : ctx.structFieldAssignment()) {
-            Map.Entry<String, StructFieldValue> entry = parseStructFieldAssignment(assignCtx);
+        overrides.put("label", label);
 
-            // Check that the field exists in the struct definition
-            // "label" is a special required field that doesn't need to be defined in the struct
-            if (!entry.getKey().equals("label") && definition.getField(entry.getKey()).isEmpty()) {
-                throw new IllegalArgumentException(
-                        "Unknown field '" + entry.getKey() + "' in struct " + structName
-                );
-            }
+        // Process optional WITH clause field overrides
+        for (SFMLParser.StructFieldOverrideContext overrideCtx : ctx.structFieldOverride()) {
+            String fieldName = overrideCtx.identifier().getText();
 
-            // Check for duplicate assignments
-            if (overrides.containsKey(entry.getKey())) {
+            // Validate that the field exists in the struct definition
+            if (definition.getField(fieldName).isEmpty()) {
                 throw new IllegalArgumentException(
-                        "Duplicate field assignment '" + entry.getKey() + "' in struct instantiation"
+                        "Unknown field '" + fieldName + "' in struct " + structName
                 );
             }
 
-            overrides.put(entry.getKey(), entry.getValue());
-        }
-
-        // Validate that label override is present
-        if (!overrides.containsKey("label")) {
-            throw new IllegalArgumentException(
-                    "Struct instantiation must include a 'label' override to bind to actual blocks"
-            );
+            StructFieldValue value = visitStructFieldValue(overrideCtx.structFieldValue());
+            overrides.put(fieldName, value);
         }
 
         StructInstance instance = new StructInstance(variableName, definition, overrides);
@@ -593,12 +586,6 @@ public StructInstance visitStructInstantiation(SFMLParser.StructInstantiationCon
         return instance;
     }
 
-    private Map.Entry<String, StructFieldValue> parseStructFieldAssignment(SFMLParser.StructFieldAssignmentContext ctx) {
-        String fieldName = ctx.identifier().getText();
-        StructFieldValue value = visitStructFieldValue(ctx.structFieldValue());
-        return new SimpleEntry<>(fieldName, value);
-    }
-
     // ===== END STRUCT DEFINITIONS =====
 
     // ===== MACRO DEFINITIONS =====
diff --git a/src/main/java/ca/teamdman/sfml/ast/LetStatement.java b/src/main/java/ca/teamdman/sfml/ast/LetStatement.java
index 9d2eb38bb..3d0b0481f 100644
--- a/src/main/java/ca/teamdman/sfml/ast/LetStatement.java
+++ b/src/main/java/ca/teamdman/sfml/ast/LetStatement.java
@@ -2,7 +2,9 @@
 
 /**
  * Represents a let statement that binds a struct instance to a variable name.
- * Example: let smelter = Furnace { label: "my furnaces" }
+ * The variable name automatically becomes the label for the struct instance.
+ * Example: let furnaces = Furnace
+ * Example with overrides: let furnaces = Furnace WITH input: NORTH SIDE
  */
 public record LetStatement(
         String variableName,
diff --git a/src/main/java/ca/teamdman/sfml/ast/StructInstance.java b/src/main/java/ca/teamdman/sfml/ast/StructInstance.java
index 55b743086..fa5f36be2 100644
--- a/src/main/java/ca/teamdman/sfml/ast/StructInstance.java
+++ b/src/main/java/ca/teamdman/sfml/ast/StructInstance.java
@@ -4,8 +4,10 @@
 import java.util.Optional;
 
 /**
- * Represents an instantiation of a struct with overrides.
- * Example: Furnace { label: "my furnaces" }
+ * Represents an instantiation of a struct with optional field overrides.
+ * The variable name from the let statement becomes the label automatically.
+ * Example: Furnace
+ * Example with overrides: Furnace WITH input: NORTH SIDE
  */
 public record StructInstance(
         String variableName,
@@ -40,14 +42,20 @@ public Optional<Label> getLabel() {
     @Override
     public String toString() {
         StringBuilder sb = new StringBuilder();
-        sb.append(definition.name()).append(" { ");
-        boolean first = true;
-        for (Map.Entry<String, StructFieldValue> entry : overrides.entrySet()) {
-            if (!first) sb.append(", ");
-            sb.append(entry.getKey()).append(": ").append(entry.getValue());
-            first = false;
+        sb.append(definition.name());
+        // Only show non-label overrides (label comes from variable name)
+        boolean hasOverrides = overrides.entrySet().stream()
+                .anyMatch(e -> !e.getKey().equals("label"));
+        if (hasOverrides) {
+            sb.append(" WITH ");
+            boolean first = true;
+            for (Map.Entry<String, StructFieldValue> entry : overrides.entrySet()) {
+                if (entry.getKey().equals("label")) continue;
+                if (!first) sb.append(", ");
+                sb.append(entry.getKey()).append(": ").append(entry.getValue());
+                first = false;
+            }
         }
-        sb.append(" }");
         return sb.toString();
     }
 }
diff --git a/src/main/resources/assets/sfm/template_programs/library_blocks.sfml b/src/main/resources/assets/sfm/template_programs/library_blocks.sfml
index ee236dcd8..ca1551bef 100644
--- a/src/main/resources/assets/sfm/template_programs/library_blocks.sfml
+++ b/src/main/resources/assets/sfm/template_programs/library_blocks.sfml
@@ -25,9 +25,9 @@ NAME "Library Blocks"
 -- Now you can use Smeltable, Furnace, and smelt macro
 -- as if they were defined in this file!
 
--- let f = Furnace { label: "my_furnace" }
+-- let my_furnace = Furnace
 -- every 20 ticks do
---     DO smelt(f, ores, ingots)
+--     DO smelt(my_furnace, ores, ingots)
 -- end
 
 -- Note: Library blocks need to exist in-world with a disk containing definitions
diff --git a/src/main/resources/assets/sfm/template_programs/protocols_and_macros.sfml b/src/main/resources/assets/sfm/template_programs/protocols_and_macros.sfml
index c2dbe7514..57ae90b3c 100644
--- a/src/main/resources/assets/sfm/template_programs/protocols_and_macros.sfml
+++ b/src/main/resources/assets/sfm/template_programs/protocols_and_macros.sfml
@@ -32,11 +32,12 @@ macro smelt(machine: Smeltable, source, dest)
     output to dest
 end
 
-let furnace = Furnace { label: "furnaces" }
-let blast = BlastFurnace { label: "blast_furnaces" }
+-- Variable names become labels automatically
+let furnaces = Furnace
+let blast_furnaces = BlastFurnace
 
 -- Use "DO" or "@" to invoke macros
 every 20 ticks do
-    DO smelt(furnace, ore_chest, ingot_chest)
-    @smelt(blast, iron_ore, iron_ingots)
+    DO smelt(furnaces, ore_chest, ingot_chest)
+    @smelt(blast_furnaces, iron_ore, iron_ingots)
 end
diff --git a/src/main/resources/assets/sfm/template_programs/structs.sfml b/src/main/resources/assets/sfm/template_programs/structs.sfml
index ffe0fe00b..082a849f6 100644
--- a/src/main/resources/assets/sfm/template_programs/structs.sfml
+++ b/src/main/resources/assets/sfm/template_programs/structs.sfml
@@ -9,21 +9,21 @@ struct Furnace
     output: BOTTOM SIDE SLOTS 2
 end
 
--- Create an instance bound to blocks labelled "furnaces"
-let smelter = Furnace { label: "furnaces" }
+-- Create an instance - the variable name becomes the label
+let furnaces = Furnace
 
 -- Use the "using" keyword to access struct fields
 every 20 ticks do
     input from ore_chest
-    output to smelter using input
+    output to furnaces using input
 
     forget
 
     input from fuel_chest
-    output retain 1 to each smelter using fuel
+    output retain 1 to each furnaces using fuel
 
     forget
 
-    input from smelter using output
+    input from furnaces using output
     output to results
 end
diff --git a/src/test/java/ca/teamdman/sfml/SFMLTests.java b/src/test/java/ca/teamdman/sfml/SFMLTests.java
index eaed480f3..45859b7d1 100644
--- a/src/test/java/ca/teamdman/sfml/SFMLTests.java
+++ b/src/test/java/ca/teamdman/sfml/SFMLTests.java
@@ -827,8 +827,7 @@ public void structBasicDefinition() {
                             output: BOTTOM SIDE SLOTS 2
                         end
 
-                        let smelter = Furnace { label: "my_furnaces" }
-
+                        let smelter = Furnace
                         every 20 ticks do
                             input from ore_chest
                             output to smelter using input
@@ -847,8 +846,7 @@ public void structWithUsingClause() {
                     output: BOTTOM SIDE SLOTS 2
                 end
 
-                let smelter = Furnace { label: "furnaces" }
-
+                let smelter = Furnace
                 every 20 ticks do
                     input from chest
                     output to smelter using input
@@ -868,21 +866,22 @@ public void structWithUsingClause() {
     }
 
     @Test
-    public void structMissingLabel() {
+    public void structWithFieldOverride() {
         var input = """
-                NAME "Missing Label Test"
+                NAME "Field Override Test"
 
                 struct Furnace
-                    input: TOP SIDE
+                    input: TOP SIDE SLOTS 0
                 end
 
-                let smelter = Furnace { input: TOP SIDE }
+                let smelter = Furnace WITH input: NORTH SIDE SLOTS 1-2
 
                 every 20 ticks do
                     input from chest
+                    output to smelter using input
                 end
                 """;
-        assertCompileErrorsPresent(input);
+        assertNoCompileErrors(input);
     }
 
     @Test
@@ -890,8 +889,7 @@ public void structUnknownStruct() {
         var input = """
                 NAME "Unknown Struct Test"
 
-                let smelter = UnknownStruct { label: "test" }
-
+                let smelter = UnknownStruct
                 every 20 ticks do
                     input from chest
                 end
@@ -908,8 +906,7 @@ public void structUnknownVariable() {
                     input: TOP SIDE
                 end
 
-                let smelter = Furnace { label: "test" }
-
+                let smelter = Furnace
                 every 20 ticks do
                     input from unknown_var using input
                 end
@@ -926,8 +923,7 @@ public void structUnknownField() {
                     input: TOP SIDE
                 end
 
-                let smelter = Furnace { label: "test" }
-
+                let smelter = Furnace
                 every 20 ticks do
                     input from smelter using unknown_field
                 end
@@ -948,8 +944,7 @@ public void structDuplicateDefinition() {
                     output: BOTTOM SIDE
                 end
 
-                let smelter = Furnace { label: "test" }
-
+                let smelter = Furnace
                 every 20 ticks do
                     input from chest
                 end
@@ -967,8 +962,7 @@ public void structDuplicateField() {
                     input: BOTTOM SIDE
                 end
 
-                let smelter = Furnace { label: "test" }
-
+                let smelter = Furnace
                 every 20 ticks do
                     input from chest
                 end
@@ -985,8 +979,7 @@ public void structSideOverride() {
                     input: TOP SIDE SLOTS 0
                 end
 
-                let smelter = Furnace { label: "furnaces" }
-
+                let smelter = Furnace
                 every 20 ticks do
                     input from chest
                     output to smelter using input BOTTOM SIDE
@@ -1006,8 +999,7 @@ public void structSlotOnlyField() {
                             hotbar: SLOTS 27-35
                         end
 
-                        let inv = Storage { label: "inventory" }
-
+                        let inv = Storage
                         every 20 ticks do
                             input from inv using main
                             output to inv using hotbar
@@ -1036,8 +1028,7 @@ public void protocolBasicDefinition() {
                             output: BOTTOM SIDE SLOTS 2
                         end
 
-                        let smelter = Furnace { label: "furnaces" }
-
+                        let smelter = Furnace
                         every 20 ticks do
                             input from chest
                             output to smelter using input
@@ -1065,8 +1056,7 @@ public void protocolMultipleImplementation() {
                             output: BOTTOM SIDE SLOTS 1
                         end
 
-                        let machine = Machine { label: "machines" }
-
+                        let machine = Machine
                         every 20 ticks do
                             input from chest
                             output to machine using input
@@ -1084,8 +1074,7 @@ public void protocolUnknownProtocol() {
                     input: TOP SIDE SLOTS 0
                 end
 
-                let smelter = Furnace { label: "test" }
-
+                let smelter = Furnace
                 every 20 ticks do
                     input from chest
                 end
@@ -1107,8 +1096,7 @@ public void protocolMissingField() {
                     input: TOP SIDE SLOTS 0
                 end
 
-                let smelter = Furnace { label: "test" }
-
+                let smelter = Furnace
                 every 20 ticks do
                     input from chest
                 end
@@ -1129,8 +1117,7 @@ public void protocolFieldTypeMismatch() {
                     input: 42
                 end
 
-                let smelter = Furnace { label: "test" }
-
+                let smelter = Furnace
                 every 20 ticks do
                     input from chest
                 end
@@ -1202,8 +1189,7 @@ macro smelt(machine: Smeltable, source, dest)
                             output to dest
                         end
 
-                        let furnace = Furnace { label: "furnaces" }
-
+                        let furnace = Furnace
                         every 20 ticks do
                             DO smelt(furnace, ore_chest, ingot_chest)
                         end
@@ -1257,8 +1243,7 @@ macro smelt(machine: Smeltable)
                     input from machine using input
                 end
 
-                let device = NonSmeltable { label: "devices" }
-
+                let device = NonSmeltable
                 every 20 ticks do
                     DO smelt(device)
                 end
@@ -1355,8 +1340,7 @@ macro smelt(machine: Smeltable, ore_source, fuel_source, dest)
                             output to dest
                         end
 
-                        let furnace = Furnace { label: "furnaces" }
-
+                        let furnace = Furnace
                         every 20 ticks do
                             DO smelt(furnace, ore_chest, fuel_chest, result_chest)
                         end
@@ -1461,8 +1445,7 @@ public void libraryWithInputOutputProtocolStruct() {
 
             use library "io_lib"
 
-            let device = IODevice { label: "devices" }
-
+            let device = IODevice
             every 20 ticks do
                 input from source_chest
                 output to device using input
@@ -1509,8 +1492,7 @@ macro transfer_through(machine: HasInput, machine2: HasOutput, src, dst)
 
             use library "transfer_lib"
 
-            let processor = Processor { label: "processors" }
-
+            let processor = Processor
             every 20 ticks do
                 DO transfer_through(processor, processor, input_chest, output_chest)
             end
@@ -1562,8 +1544,7 @@ macro process(device: Processable, src, dst)
 
             use library "combined_lib"
 
-            let machine = Machine { label: "machines" }
-
+            let machine = Machine
             every 20 ticks do
                 DO process(machine, source, dest)
             end
@@ -1619,7 +1600,8 @@ macro transfer(device: IOCapable, src, dst)
             NAME "Valid Usage"
             use library "constrained_lib"
 
-            let device = ValidDevice { label: "devices" }
+            let device = ValidDevice
+
             every 20 ticks do
                 DO transfer(device, a, b)
             end
@@ -1631,7 +1613,8 @@ DO transfer(device, a, b)
             NAME "Invalid Usage"
             use library "constrained_lib"
 
-            let device = InvalidDevice { label: "devices" }
+            let device = InvalidDevice
+
             every 20 ticks do
                 DO transfer(device, a, b)
             end
@@ -1697,7 +1680,8 @@ macro smelt(machine: HasInput, machine2: HasOutput, src, dst)
             use library "struct_lib"
             use library "macro_lib"
 
-            let furnace = Furnace { label: "furnaces" }
+            let furnace = Furnace
+
             every 20 ticks do
                 DO smelt(furnace, furnace, ore_chest, ingot_chest)
             end
@@ -1746,8 +1730,7 @@ macro smelt(machine: Smeltable, source, dest)
                             output to dest
                         end
 
-                        let furnace = Furnace { label: "furnaces" }
-
+                        let furnace = Furnace
                         every 20 ticks do
                             DO smelt(furnace, ore_chest, ingot_chest)
                         end
@@ -1777,8 +1760,7 @@ public void protocolWithAllFieldTypes() {
                             num: 42
                         end
 
-                        let impl = Implementation { label: "test" }
-
+                        let impl = Implementation
                         every 20 ticks do
                             input from chest
                         end
diff --git a/vscodeextension/super-factory-manager-language/syntaxes/SFML.g4 b/vscodeextension/super-factory-manager-language/syntaxes/SFML.g4
index 868d21e41..9358a19e1 100644
--- a/vscodeextension/super-factory-manager-language/syntaxes/SFML.g4
+++ b/vscodeextension/super-factory-manager-language/syntaxes/SFML.g4
@@ -69,8 +69,8 @@ macroLabelAccess : identifier                                               #Mac
                  ;
 
 letStatement : LET identifier EQ_SYMBOL structInstantiation ;
-structInstantiation : identifier LBRACE structFieldAssignment (COMMA structFieldAssignment)* COMMA? RBRACE ;
-structFieldAssignment : identifier COLON structFieldValue ;
+structInstantiation : identifier (WITH structFieldOverride (COMMA structFieldOverride)*)? ;
+structFieldOverride : identifier COLON structFieldValue ;
 
 //
 // TRIGGERS
@@ -325,8 +325,6 @@ NAME            : N A M E ;
 STRUCT          : S T R U C T ;
 LET             : L E T ;
 USING           : U S I N G ;
-LBRACE          : '{' ;
-RBRACE          : '}' ;
 
 // PROTOCOL SYMBOLS
 PROTOCOL        : P R O T O C O L ;

From 5081e3619d20ab0ef69b7f53a67228c5b1cc6012 Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Mon, 26 Jan 2026 00:31:39 +0100
Subject: [PATCH 32/33] docs: add WITH clause example to structs template

---
 src/main/resources/assets/sfm/template_programs/structs.sfml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/main/resources/assets/sfm/template_programs/structs.sfml b/src/main/resources/assets/sfm/template_programs/structs.sfml
index 082a849f6..0bd225af2 100644
--- a/src/main/resources/assets/sfm/template_programs/structs.sfml
+++ b/src/main/resources/assets/sfm/template_programs/structs.sfml
@@ -12,6 +12,9 @@ end
 -- Create an instance - the variable name becomes the label
 let furnaces = Furnace
 
+-- Override default fields with the WITH clause
+let side_loaders = Furnace WITH input: NORTH SIDE SLOTS 0-2
+
 -- Use the "using" keyword to access struct fields
 every 20 ticks do
     input from ore_chest

From a34904da7bb055dcc79e7c3db590ef59ba77c8dc Mon Sep 17 00:00:00 2001
From: Reinder Noordmans <reindernoordmans@icloud.com>
Date: Mon, 26 Jan 2026 00:42:15 +0100
Subject: [PATCH 33/33] fix: truncate long library names and add scroll on
 hover

---
 .../sfm/client/screen/LibraryScreen.java      | 65 ++++++++++++++++++-
 1 file changed, 63 insertions(+), 2 deletions(-)

diff --git a/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java b/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
index a1e5548b3..5b754a3d6 100644
--- a/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
+++ b/src/main/java/ca/teamdman/sfm/client/screen/LibraryScreen.java
@@ -51,6 +51,10 @@ public class LibraryScreen extends AbstractContainerScreen<LibraryContainerMenu>
     private static final int WARNING_BAR = 0x30FFFF40;    // Warning highlight
 
     private int hoveredLibraryEntry = -1;
+    private int lastHoveredLibraryEntry = -1;
+    private long hoverStartTime = 0;
+    private static final long SCROLL_DELAY_MS = 500;      // Wait before scrolling starts
+    private static final float SCROLL_SPEED = 30f;        // Pixels per second
 
     public LibraryScreen(
             LibraryContainerMenu menu,
@@ -177,6 +181,10 @@ public void render(
                 // Draw hover highlight bar or status bar
                 if (hovered) {
                     hoveredLibraryEntry = i;
+                    if (lastHoveredLibraryEntry != i) {
+                        hoverStartTime = System.currentTimeMillis();
+                        lastHoveredLibraryEntry = i;
+                    }
                     fill(poseStack, screenX + 3, contentY - 1, screenRight - 3, contentY + font.lineHeight + 1, barColor);
                 } else if (entry.hasErrors()) {
                     fill(poseStack, screenX + 3, contentY - 1, screenRight - 3, contentY + font.lineHeight + 1, ERROR_BAR);
@@ -186,12 +194,60 @@ public void render(
 
                 // Cursor indicator and library name
                 String cursor = hovered ? "> " : "  ";
-                font.drawShadow(poseStack, cursor + entry.name(), textX, contentY, textColor);
+                int cursorWidth = font.width(cursor);
 
                 // Slot number right-aligned
                 String slotText = "[" + entry.slotIndex() + "]";
                 int slotWidth = font.width(slotText);
-                font.drawShadow(poseStack, slotText, screenRight - 6 - slotWidth, contentY, TEXT_SECONDARY);
+                int slotX = screenRight - 6 - slotWidth;
+
+                // Calculate available width for library name (between cursor and slot number)
+                int nameStartX = textX + cursorWidth;
+                int maxNameWidth = slotX - nameStartX - 4; // 4px padding before slot
+
+                String name = entry.name();
+                int nameWidth = font.width(name);
+
+                // Draw cursor
+                font.drawShadow(poseStack, cursor, textX, contentY, textColor);
+
+                // Draw library name with truncation or scrolling
+                if (nameWidth <= maxNameWidth) {
+                    // Name fits - draw normally
+                    font.drawShadow(poseStack, name, nameStartX, contentY, textColor);
+                } else if (hovered) {
+                    // Hovered and too long - scroll the text
+                    long currentTime = System.currentTimeMillis();
+                    long hoverDuration = currentTime - hoverStartTime;
+
+                    if (hoverDuration > SCROLL_DELAY_MS) {
+                        // Calculate scroll offset - infinite scroll with pause at start
+                        float scrollTime = (hoverDuration - SCROLL_DELAY_MS) / 1000f;
+                        int scrollDistance = nameWidth + 20; // Full width plus gap before repeat
+                        float scrollOffset = (scrollTime * SCROLL_SPEED) % scrollDistance;
+
+                        // Enable scissor to clip text
+                        enableScissor(nameStartX, contentY - 1, slotX - 4, contentY + font.lineHeight + 1);
+                        font.drawShadow(poseStack, name, nameStartX - (int) scrollOffset, contentY, textColor);
+                        // Draw second copy for seamless loop
+                        font.drawShadow(poseStack, name, nameStartX - (int) scrollOffset + scrollDistance, contentY, textColor);
+                        disableScissor();
+                    } else {
+                        // Still in delay period - show truncated with ellipsis
+                        enableScissor(nameStartX, contentY - 1, slotX - 4, contentY + font.lineHeight + 1);
+                        font.drawShadow(poseStack, name, nameStartX, contentY, textColor);
+                        disableScissor();
+                    }
+                } else {
+                    // Not hovered and too long - truncate with ellipsis
+                    String ellipsis = "...";
+                    int ellipsisWidth = font.width(ellipsis);
+                    String truncated = font.plainSubstrByWidth(name, maxNameWidth - ellipsisWidth) + ellipsis;
+                    font.drawShadow(poseStack, truncated, nameStartX, contentY, textColor);
+                }
+
+                // Draw slot number
+                font.drawShadow(poseStack, slotText, slotX, contentY, TEXT_SECONDARY);
 
                 contentY += font.lineHeight + 3;
 
@@ -199,6 +255,11 @@ public void render(
                 if (contentY > this.topPos + this.imageHeight - font.lineHeight - 10) break;
             }
         }
+
+        // Reset scroll state when no longer hovering any entry
+        if (hoveredLibraryEntry == -1) {
+            lastHoveredLibraryEntry = -1;
+        }
     }
 
     @Override