Documentation, Guides, Tests, and Struct Node Output Refactor (#108)

* Now capturing error and timing metrics, new Divide and DivideToArray nodes

* start of showing node execution times and error messages

* capturing timings of nodes

* timing updates

* struct node output port refactor

* Execution times on webpage update as you make changes

* standardized node naming

* fixed resizing issue

* Documentation, new nodes spline: position, positions for array, tangent, tangents for array

* import manifest into editor

* Editor section of unity integration

* flake update

* flake update

* fix: duplicate material names in obj

* fix: npmDepsHash skip cache mismatch error (#111)

We add `-Lo` to print verbose build logs so that errors [here](https://github.com/EliCDavis/polyform/actions/runs/16831757233/job/47680959627#step:5:214) will display the actual hash mismatch error [log](https://github.com/EliCDavis/polyform/actions/runs/16832252332/job/47682633319#step:5:214) so we know which to update.

Adds two small [Nix Flake App](https://nix.dev/manual/nix/2.28/command-ref/new-cli/nix3-run.html#apps) scripts to both document how to update sri files or clear Github Action cache, as well as make them easy to re-run.
Tried to find a way to make SRI updates runnable without nix, but since both utilties are fairly bespoke programs to fetch/install, it seemed easier to just keep it in a derivation to be run with WSL or a linux container.

* Doc update

---------

Co-authored-by: Kaleb Pace <[email protected]>

Author: EliCDavis

.github/workflows/build.yml

@@ -1,12 +1,14 @@
 name: Build
 
 on:
-    push:
-        branches: [ "main" ]
-    pull_request:
-        branches: [ "main" ]
-    # Allows manual triggering
-    workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  # Allows manual triggering
+  workflow_dispatch:
 
 jobs:
   check:
@@ -26,7 +28,7 @@ jobs:
       - uses: DeterminateSystems/flakehub-cache-action@main
 
       - name: Restore Nix-cached Release Artifacts
-        run: nix build .#release -o ./artifacts
+        run: nix build .#release -Lo ./artifacts
 
   pages:
     runs-on: ubuntu-latest
@@ -36,4 +38,4 @@ jobs:
       - uses: DeterminateSystems/flakehub-cache-action@main
 
       - name: Restore Nix-cached Pages Artifacts
-        run: nix build .#pages -o ./dist
+        run: nix build .#pages -Lo ./dist

.github/workflows/flake-update.yml

@@ -2,7 +2,7 @@ name: update-flake-lock
 on:
   workflow_dispatch: # allows manual triggering
   schedule:
-    - cron: "0 0 * * 0" # runs weekly on Sunday at 00:00
+    - cron: "0 0 1 * *" # runs weekly on Sunday at 00:00
 
 jobs:
   lockfile:

.github/workflows/release.yml

@@ -28,7 +28,7 @@ jobs:
       - uses: DeterminateSystems/flakehub-cache-action@main
 
       - name: Restore Nix-cached Release Artifacts
-        run: nix build .#release -o ./artifacts
+        run: nix build .#release -Lo ./artifacts
 
       - name: Publish GitHub Release
         run: |
@@ -45,7 +45,7 @@ jobs:
       - uses: DeterminateSystems/flakehub-cache-action@main
 
       - name: Restore Nix-cached Pages Artifacts
-        run: nix build .#pages -o ./dist
+        run: nix build .#pages -Lo ./dist
 
       - name: Setup Pages
         uses: actions/configure-pages@v4

README.md

@@ -2,4 +2,13 @@
 
 ## Guides
 
-* [Creating a Custom Node](./guides/CreatingNodes.md)
+* [Polyform Concepts](./guides/Concepts/README.md)
+* Adding New Nodes
+    * [Creating a Custom Node](./guides/CreatingNodes/README.md)
+    * [Manifests](./guides/CreatingManifests/README.md)
+    * [Best Practices](./guides/NodeBestPractices/README.md)
+* [Unity Integration](./guides/UnityIntegration/README.md)
+
+## Resources
+
+[Recomended Reading](./resources/README.md)

docs/README.md

@@ -0,0 +1,19 @@
+[Table of Contents](../../README.md)
+
+# Concepts
+
+## Variables
+
+Variables are high-level values that a graph exposes for external control. They act as inputs to the procedural generation process. Changing them alters the graph’s behavior without modifying the graph’s structure.
+
+Variables can represent anything from a single number or color to more complex data like positions, textures, or mesh data.
+
+## Profiles
+
+Profiles are saved sets of variable values. They make it easy to store and reuse specific configurations for a graph.
+
+## Manifest
+
+A manifest is the structured output of running a graph with a given set of variables.
+
+It describes what the graph produced, generally including references to generated geometry, textures, or metadata.

docs/guides/Concepts/README.md

@@ -0,0 +1,104 @@
+Previous: [Creating a Custom Node](../CreatingNodes/README.md) | [Table of Contents](../../README.md) | Next: [Best Practices](../NodeBestPractices/README.md)
+
+# Creating Manifest Nodes
+
+Polyform operates on [Directed Acyclic Graphs (DAGs)](https://en.wikipedia.org/wiki/Directed_acyclic_graph), where each node performs a specific task and connects to other nodes through inputs and outputs.
+
+Manifest nodes are special types of nodes that **define the final output of a graph**, typically writing one or more files to the filesystem. 
+
+## What is a Manifest?
+
+A **manifest** is a structure that encapsulates **a set of named entries**, each representing an output artifact such as an image, mesh, or any other serializable content. It also optionally defines a **"main" entry**, which can help tell viewers the first entry to download. 
+
+For example, if we have a manifest for a textured GLTF, you might have 2 entries: the GLTF itself, and a seperate image file the GLTF references. In this scenario, we'd set the GLTF file to be the main entry that a viewer would initially download.
+
+Here's the core structure used for manifests:
+
+```go
+type Entry struct {
+	Metadata map[string]any `json:"metadata"` // Descriptive metadata about the artifact
+	Artifact Artifact       `json:"-"`        // The actual data to be written
+}
+
+type Manifest struct {
+	Main    string           `json:"main"`    // Optional: name of the main entry
+	Entries map[string]Entry `json:"entries"` // All entries in the manifest
+}
+```
+
+## Artifacts
+
+The `Artifact` interface defines what it means to be a serializable output. Any type that implements this interface can be written as part of a manifest.
+
+```go
+type Artifact interface {
+	Write(io.Writer) error // Defines how the artifact is written to disk or elsewhere
+	Mime() string          // Describes the type of content (e.g., "image/png", "application/json")
+}
+```
+
+Here's a minimal example for a text file:
+
+```go
+type TextArtifact struct {
+	Content string
+}
+
+func (ta TextArtifact) Write(w io.Writer) error {
+	_, err := io.WriteString(w, ta.Content)
+	return err
+}
+
+func (ta TextArtifact) Mime() string {
+	return "text/plain"
+}
+```
+
+Then you can include this in your manifest entry:
+
+```go
+entry := manifest.Entry{
+	Metadata: map[string]any{"type": "text"},
+	Artifact: TextArtifact{Content: "Hello World!"},
+}
+```
+
+## Creating a Manifest Node
+
+A manifest node in Polyform is simply a node whose **output type is `manifest.Manifest`**. When Polyform runs a graph and reaches this node, it knows how to gather the manifest entries and process them as final outputs.
+
+Here’s an example of what a simple manifest node might look like:
+
+```go
+type MyManifestNode struct {
+	Image nodes.Output[image.Image] `description:"The image to export"`
+	Path  nodes.Output[string]      `description:"Path to export to"`
+}
+
+func (mmn MyManifestNode) Output(out *nodes.StructOutput[manifest.Manifest]) {
+	img := nodes.TryGetOutputValue(out, mmn.Image, nil)
+	if img == nil {
+		return
+	}
+
+	entry := manifest.Entry{
+		Metadata: map[string]any{
+			"description": "Exported PNG image",
+		},
+		Artifact: &manifest.ImageArtifact{
+			Image: img,
+			MimeType: "image/png",
+		},
+	}
+
+	entryPath := nodes.TryGetOutputValue(out, mmn.Path, "export.png")
+	out.Set(manifest.Manifest{
+		Main: entryPath,
+		Entries: map[string]manifest.Entry{
+			entryPath: entry,
+		},
+	})
+}
+```
+
+> **Note**: `manifest.ImageArtifact` in this example is a hypothetical implementation of the `Artifact` interface that knows how to write an image as PNG.

docs/guides/CreatingManifests/README.md

@@ -1,14 +1,17 @@
+[Table of Contents](../../README.md) | Next: [Manifests](../CreatingManifests/README.md)
+
 # Creating a Custom Node
 
 In Polyform, a node generally represents a single operation in a procedural graph. 
 
-Inputs to nodes are other nodes' outputs, and outputs are computed dynamically as the graph executes.
+* Inputs to nodes are other nodes' outputs.
+* Outputs are computed on demand as the graph executes.
 
 ## Defining a Node
 
-Nodes generally start as a struct, where the fields of that struct represent it's connections to other node's output.
+Nodes generally start as a struct, where the fields of that struct represent its connections to other node's output.
 
-For the sake of presenting information to the user, as well as automatically generating documentation, you can define descriptions for node as well as each of it's inputs.
+For the sake of presenting information to the user, as well as automatically generating documentation, you can define descriptions for the node as well as each of its inputs.
 
 ```go
 type MathNode struct {
@@ -23,42 +26,45 @@ func (MathNode) Description() string {
 
 ### Defining Outputs 
 
-Any method on a struct that returns a  `nodes.StructOutput[T]` is automatically treated as an output port by the system. `StructOutput[T]` acts as a wrapper around the value you want to output for supporting things like error handling.
+Any method on a struct that accepts a `*nodes.StructOutput[T]` is automatically treated as an output port by the system. `StructOutput[T]` acts as a wrapper around the value you want to output, supporting things like timing operations and error handling.
 
 ```go
-func (cn MathNode) Add() nodes.StructOutput[float64] {
+func (cn MathNode) Add(out *nodes.StructOutput[float64]) {
     a := cn.A.Value()
     b := cn.B.Value()
-	return nodes.NewStructOutput(a + b)
+	out.Set(a + b)
 }
 ```
 
-However, when implementing the function, a node should never assume any of its input ports are set. Calling `Value()` on a `nil` input port will cause the runtime to panic and the graph execution to halt. The utility `nodes.TryGetOutputValue` has been introduced that will attempt to take the value of an input port if it exists, and returns a fallback value when the input port is `nil`. Updating our code to be more safe results in our `Add` function looking like:
+However, when implementing the function, a node should never assume any of its input ports are set. Calling `Value()` on a `nil` input port will cause the runtime to panic and the graph execution to halt. The utility `nodes.TryGetOutputValue` has been introduced that will attempt to take the value of an input port if it exists, and returns a fallback value when the input port is `nil`. `TryGetOutputValue` also keeps up with how much time it takes for the input to execute, subtracting it from the `MathNode`'s execution time, allowing for proper reporting of performance on a per node basis. Updating our code to be more safe results in our `Add` function looking like:
 
 ```go
-func (mn MathNode) Add() nodes.StructOutput[float64] {
-    a := nodes.TryGetOutputValue(mn.A, 0)
-    b := nodes.TryGetOutputValue(mn.B, 0)
-	return nodes.NewStructOutput(a + b)
+func (mn MathNode) Add(out *nodes.StructOutput[float64]) {
+    a := nodes.TryGetOutputValue(out, mn.A, 0)
+    b := nodes.TryGetOutputValue(out, mn.B, 0)
+	out.Set(a + b)
 }
 ```
 
-Sometimes, the current input into a node is in effect "invalid" and no real computation can be done. In these scenarios a _sensible_ default value needs to be returned. Unfortunately, what "_sensible_" means is dependent upon the kind of operations being performed by the node, but a good rule of thumb is returning the ["zero" value](https://go.dev/ref/spec#The_zero_value) of the datatype.
+Sometimes, the current input into a node is effectively "invalid" and no real computation can be done. In these scenarios a _sensible_ default value needs to be returned. Unfortunately, what "_sensible_" means is dependent upon the kind of operations being performed by the node, but a good rule of thumb is returning the ["zero" value](https://go.dev/ref/spec#The_zero_value) of the datatype.
 
 Before we return our sensible value, we can capture an error to alert the graph system that something has gone wrong.
 
 ```go
-func (mn MathNode) Divide() nodes.StructOutput[float64] {
-    a := nodes.TryGetOutputValue(mn.A, 0)
-    b := nodes.TryGetOutputValue(mn.B, 0)
+func (mn MathNode) Divide(out *nodes.StructOutput[float64]) {
+    a := nodes.TryGetOutputValue(out, mn.A, 0)
+    b := nodes.TryGetOutputValue(out, mn.B, 0)
 
     if b == 0 {
-        out := nodes.NewStructOutput[float64](0.)
+		// By default, the output is the zero value already, so this line 
+		// effectively acts as a no-op, and is kept for demonstration purposes
+		// only.
+		out.Set(0) 
         out.CaptureError(errors.New("can't divide by 0"))
-        return out
+        return
     }
 
-	return nodes.NewStructOutput(a / b)
+	out.Set(a / b)
 }
 ```
 
@@ -78,22 +84,20 @@ func (MathNode) DivideDescription() string {
 
 ### Array Inputs
 
-If the operation you're performing can take any number of inputs, you can define your input as type `[]nodes.Output[T]`. Doing so allows users to wire up multiple nodes into the same input slot.
+If the operation you're performing can take any number of inputs, you can define your input as type `[]nodes.Output[T]`. Doing so allows users to wire up multiple nodes into the same input slot. You can then use `nodes.GetOutputValues` to call resolve all inputs, creating timings while doing so.
 
 ```go
 type SumNode struct {
 	Values []nodes.Output[float64] `description:"The nodes to sum"`
 }
 
-func (sn SumNode) Sum() nodes.StructOutput[float64] {
+func (sn SumNode) Sum(out *nodes.StructOutput[float64]) {
 	var total float64
-	for _, v := range sn.Values {
-		if v == nil {
-			continue
-		}
-		total += v.Value()
+	values := nodes.GetOutputValues(out, sn.Values)
+	for _, v := range values {
+		total += v
 	}
-	return nodes.NewStructOutput(total)
+	out.Set(total)
 }
 ```
 
@@ -103,7 +107,7 @@ Now that you've defined your node, you need to take steps to include it in a bui
 
 ### Registering the Package
 
-The standard way to register your nodes with the graph system is to define a `init` function in your package. You can read more about it's [specifics of execution here](https://go.dev/doc/effective_go#init).
+The standard way to register your nodes with the graph system is to define a `init` function in your package. You can read more about its [specifics of execution here](https://go.dev/doc/effective_go#init).
 
 Inside the init function, you create a `TypeFactory` which collects all the types your package wants to register. Then you pass that factory to `generator.RegisterTypes(factory)` to integrate your custom nodes into Polyform’s node registry.