From 1fca813797368e57c883a121c720566671b03459 Mon Sep 17 00:00:00 2001
From: Keavon Chambers <keavon@keavon.com>
Date: Mon, 6 May 2024 18:21:15 -0700
Subject: [PATCH] Add initial Graphene docs to the contributor guide (#1686)

* Graphene documentation

* Polishing edits
---
 .../introduction/features-and-limitations.md  |   4 +
 .../volunteer/guide/graphene/_index.md        | 108 ++++++++++++++++++
 .../guide/graphene/networks-and-nodes.md      |  24 ++++
 .../volunteer/guide/product-design/_index.md  |   2 +-
 .../volunteer/guide/projects/_index.md        |   2 +-
 .../guide/projects/student-projects.md        |   6 +-
 website/sass/base.scss                        |  73 +++++-------
 website/sass/book.scss                        |   6 +
 8 files changed, 174 insertions(+), 51 deletions(-)
 create mode 100644 website/content/volunteer/guide/graphene/_index.md
 create mode 100644 website/content/volunteer/guide/graphene/networks-and-nodes.md

diff --git a/website/content/learn/introduction/features-and-limitations.md b/website/content/learn/introduction/features-and-limitations.md
index f214b575..404f2d31 100644
--- a/website/content/learn/introduction/features-and-limitations.md
+++ b/website/content/learn/introduction/features-and-limitations.md
@@ -40,6 +40,10 @@ Starting from the left, the <img src="https://static.graphite.rs/content/learn/i
 Next, that is fed into the <img src="https://static.graphite.rs/content/learn/introduction/features-and-limitations/circular-repeat-node__2.avif" onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" onload="this.width /= 2" style="vertical-align: middle" alt="Circular Repeat" /> node which has several *parameters* you can modify and get different output data based on your choices, like in these examples:
 
 <style class="table-1-style">
+.table-1-style + table {
+	width: auto;
+}
+
 .table-1-style + table td {
 	vertical-align: middle;
 	text-align: center;
diff --git a/website/content/volunteer/guide/graphene/_index.md b/website/content/volunteer/guide/graphene/_index.md
new file mode 100644
index 00000000..1070528e
--- /dev/null
+++ b/website/content/volunteer/guide/graphene/_index.md
@@ -0,0 +1,108 @@
++++
+title = "Graphene"
+template = "book.html"
+page_template = "book.html"
+
+[extra]
+order = 3 # Chapter number
+js = ["video-embed.js"]
++++
+
+**Graphene** is the node graph engine that powers the Graphite editor.
+
+It's hard to describe in one sentence precisely what Graphene is, because it's a technology that serves several roles when viewed from different angles. But to get a feel for what it encompasses, here is a list of some of its purposes:
+
+- Render engine
+- Runtime environment
+- Procedural data processor
+- Node-based scripting system
+- Compiled programming language
+- Compiler toolchain built around `rustc`
+
+## Background
+
+### Artwork as a program
+
+Artwork created in Graphite is represented as a node graph that generates the graphical content authored by the user. This document is essentially source code for a program in the Graphene language. Modifying the graph (like adding a layer, changing a node's parameter, or updating a node's data every frame while interactively drawing a shape) changes the actual program that generates and renders the artwork. This program must be recompiled and executed every frame a change is made.
+
+Nodes are functions that run algorithms related to graphical operations. Some may read bitmap images from disk, others may generate procedural patterns, and more may be used for compositing and blending. Vector nodes can also produce shapes, alter their geometry, and apply styling and effects. Put together, a full document is built from just its interconnected nodes— producing a complete work of art generated entirely with algorithms and data.
+
+### Graph executors as programming languages
+
+Every node-based application needs to run its node graph to compute the resulting data. Execution occurs in an order that depends on the shape of the graph so that every node has the data it needs to compute its output.
+
+A procedural graph executor, in its basic form, is a simple system that executes functions in the appropriate order. It feeds information between nodes and caches that data for reuse between executions so that only changed branches of the graph have to be computed again. The system, as described, is the approach commonly used by virtually all node-based apps.
+
+Crucially, the execution flow is handled at runtime so there is some overhead during every run. By analogy to programming languages, this traditional execution model acts like an interpreted language. But interpreted languages are famously slow, and we don't want Graphite leaving performance on the table.
+
+In designing Graphene, we decided to take a more advanced approach that could yield many of the benefits of a compiled language— code inlining, compiler optimizations, and a philosophy of offloading invariant enforcement to the type system. Instead of building a simple graph interpreter where functions (nodes) are run as user input changes, we designed a system that dynamically executes the graph with a variable degree of pre-compiled optimizations where bits and pieces are recompiled and patched in while the user modifies the artwork (and graph) every frame. Thereby, Graphene can dynamically range between an interpreted language, a JIT-optimized language, and a fully compiled language.
+
+## Technical overview
+
+### The latency/performance tradeoff
+
+While working in Graphite, multiple needs arise for speed in different contexts. While making interactive changes, the user needs feedback as quickly as possible. While panning and zooming the canvas or playing an animation, the user cares about smoothness and responsiveness. When procedural artwork is exported as a standalone program that processes data at runtime (like as part of an image processing web server or embedded within a game engine), performance is the sole concern.
+
+This sliding scale of latency/performance concerns maps directly to programming language concepts. Interpreted languages run immediately, but with slow runtime performance. JIT-optimized languages also run nearly without delay, but with less overhead than an interpreter since it can dynamically balance its effort towards optimizing and executing code. Compiled languages take upfront time to compile, but run with less overhead. A choice of optimization levels can be applied to further trade initial compilation time for runtime performance.
+
+We designed Graphene to operate in all three regimes:
+
+| Regime      | Usage                                                                 |
+|:------------|:----------------------------------------------------------------------|
+| Interpreted | While editing. Simple and currently the only mode that's implemented. |
+| JIT         | While editing. Dynamically bridges the gap between both other regimes by selectively substituting branches of the graph with interpreted and compiled nodes to keep latency low and work towards higher execution performance. |
+| Compiled    | When exported. The entire graph is compiled as a standalone program.  |
+
+### Building upon the Rust compiler
+
+Nodes are functions written in Rust and every node has precompiled bytecode that ships with Graphite for use in the interpreted regime. The graph `input` → `A` → `B` → `C` → `output` is equivalent to the Rust statement `let output = C(B(A(input)));`. Graphene can either execute `A`, `B`, and `C` sequentially in its interpreted regime, or its JIT and compiled regimes can generate that Rust statement and compile it with the Rust compiler, `rustc`. The inlined and optimized bytecode can then be substituted for those three nodes in the JIT regime.
+
+Graphene figures out which branches of the graph to compile and substitute as part of the JIT process while the user is authoring content in Graphite. While editing the graph, as changes occur to specific nodes, their surrounding graph branches drop back down to using the slower interpreted nodes. Then the JIT system works its way back up to faster execution over time by gradually compiling and swapping in larger optimized parts of the overall graph.
+
+The fully compiled regime is used only when the user exports the procedural artwork as a standalone program. For example, a CLI program may read a string input argument (like a name) and procedurally generate an output image file (like a birthday card).
+
+### Compile server
+
+The three regimes have thus far been only a description of the eventual architecture direction. The interpreted regime is currently the only mode implemented in Graphene. The other two will require access to `rustc` which will necessitate the compile server that we will finish building and then publicly host for Graphite users in the future. Users of the desktop version of Graphite, utilizing [Tauri](https://tauri.app/), will be able to use an embedded `rustc` if the user has opted to download the Rust toolchain while installing Graphite.
+
+Without a compile server, all the nodes are precompiled when Graphite is built. The node registry (in the file `node_registry.rs`) currently exists to allow the interpreted executor to find the Rust functions that correspond to each node with its appropriate type signature. Nodes support generics, so it's currently necessary to list every forseeable concrete type signature in the registry until the compile server can generate bytecode for less common type combinations on-the-fly.
+
+### GPU compute shaders
+
+Further building upon the Rust compiler toolchain, we employ the [`rust-gpu`](https://github.com/EmbarkStudios/rust-gpu) compiler backend for `rustc` which generates compute shaders that get executed on the GPU. This means we can write the same code to implement nodes that run on both CPU and GPU. (Although in practice, some nodes may need GPU-specific versions suited for the architectural limitations of GPU programming.) And we don't have to use a separate shader language!
+
+### A language within a language
+
+While Graphene is a programming language, it is also foundationally built upon the Rust language. We don't just use the Rust compiler, but we also employ its type system, traits, data structures, standard library, and crate ecosystem. The data that flows between nodes are Rust types (like structs, enums, tuples, primitives, and collections). Graphene's generic type system uses Rust's trait definitions in its enforcement of type safety and type inference.
+
+### Graphene language concepts
+
+Since Graphene is fundamentally a programming language, throughout this documentation we will use analogies which correlate Graphene concepts with their counterparts from traditional programming language theory. Here is an at-a-glance overview:
+
+| Graphene concept  | Programming language concept         |
+|:------------------|:-------------------------------------|
+| Node              | Function                             |
+| Graphite editor   | IDE/text editor                      |
+| Document          | Source code                          |
+| Graph/network     | Abstract syntax tree (AST)           |
+| Graph compilation | Linking/JIT optimization/compilation |
+| Graph execution   | Program execution                    |
+
+<!-- Our philosophy of building (bootstrapping) our own higher-level language features from the language itself -->
+<!-- Primary inputs/outputs, secondary inputs/outputs, `.eval()`, recompiling when secondary input values are updated but not when primary input data is updated -->
+<!-- Compose nodes and automatic/manual composition -->
+<!-- Extract/inject nodes and metaprogramming -->
+<!-- Cache nodes and stable node IDs -->
+<!-- Graph rewriting step (currently used only to remove Identity nodes),
+	 at various points in the compilation process,
+	 based on rules akin to an optimizing compiler -->
+<!-- Borrow tree -->
+<!-- Document nodes, proto nodes, and networks (must be: acyclic) -->
+<!-- Lambdas -->
+<!-- Graph compilation process -->
+<!-- The compilation server -->
+<!-- Code structure overview -->
+<!-- Guide for implementing a node -->
+<!-- The `Node` trait -->
+<!-- Generics, type inference, type erasure, and the node registry -->
+<!-- Monitor nodes -->
diff --git a/website/content/volunteer/guide/graphene/networks-and-nodes.md b/website/content/volunteer/guide/graphene/networks-and-nodes.md
new file mode 100644
index 00000000..1f21dbcf
--- /dev/null
+++ b/website/content/volunteer/guide/graphene/networks-and-nodes.md
@@ -0,0 +1,24 @@
++++
+title = "Networks and nodes"
+
+[extra]
+order = 1 # Page number after chapter intro
++++
+
+In Graphite, users build their artwork by connecting nodes together in a graph. When they want to organize and reuse a complex group of nodes, those may be encapsulated together as a subgraph in which one parent node represents the functionality of its children. In fact, many of the nodes provided in Graphite are themselves subgraphs built out of other nodes.
+
+Double-clicking on nodes backed by a subgraph will display the subgraph's interior. Double-clicking nodes that are, instead, backed directly by Rust source code will open a code editor.
+
+Any (sub)graph can import/export data from/to the outside world. For example, a reusable subgraph may receive an imported image then use several nodes to process it and finally export the result. Or the root-level artwork graph may import the animation timestamp and render a frame of the artwork then export it to the canvas.
+
+In the Graphite editor UI, here is an example graph of artwork that imports no data but exports its content to the canvas:
+
+<img src="https://static.graphite.rs/content/index/gui-mockup-nodes__5.avif" onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" alt="Node graph UI mockup" data-carousel-image />
+
+The graph shown above represents the full artwork, meaning it's the root-level graph in its document. But there is nothing special about that graph compared to any subgraph. To avoid the confusion of calling it a graph or subgraph which comes with implications about user-facing concepts in the context of a document, we will use the less-ambiguous term **network** in the context of Graphene's internal concepts and code base.
+
+## Networks
+
+A node network can be thought of as a box containing a finite set of nodes that are connected together as a directed acyclic graph (DAG). The network is only concerned with its own node-to-node data flow. But to interact with the outside world, data can be imported into the network and exported out of it. From the inside, those imported/exported data sources/destinations are connected to the other nodes in the network. From the outside, a network can be considered a "black box" that is simply fed inputs and can be executed to produce outputs.
+
+***More coming soon...***
diff --git a/website/content/volunteer/guide/product-design/_index.md b/website/content/volunteer/guide/product-design/_index.md
index 93fd304b..48efda62 100644
--- a/website/content/volunteer/guide/product-design/_index.md
+++ b/website/content/volunteer/guide/product-design/_index.md
@@ -4,7 +4,7 @@ template = "book.html"
 page_template = "book.html"
 
 [extra]
-order = 4 # Chapter number
+order = 5 # Chapter number
 +++
 
 **NOTE: Developers probably don't need to read this chapter.**
diff --git a/website/content/volunteer/guide/projects/_index.md b/website/content/volunteer/guide/projects/_index.md
index c72e585f..bc964a4a 100644
--- a/website/content/volunteer/guide/projects/_index.md
+++ b/website/content/volunteer/guide/projects/_index.md
@@ -4,7 +4,7 @@ template = "book.html"
 page_template = "book.html"
 
 [extra]
-order = 3 # Chapter number
+order = 4 # Chapter number
 +++
 
 Graphite is built from a number of separate projects, each with a distinct focus. New developers may choose to specialize in one or more area without having to attain a working knowledge of the entire codebase. This chapter details each project's purpose, what knowledge or background is best suited for getting involved with it, and how to begin making useful contributions. Opportunities also exist for contributing to specific self-contained sub-projects for students interested in completing a Google Summer of Code or other internship program, a university capstone project, or another similar endeavor.
diff --git a/website/content/volunteer/guide/projects/student-projects.md b/website/content/volunteer/guide/projects/student-projects.md
index 510f159c..f02c9e0a 100644
--- a/website/content/volunteer/guide/projects/student-projects.md
+++ b/website/content/volunteer/guide/projects/student-projects.md
@@ -27,7 +27,7 @@ You are encouraged to reference the project idea list below to find several pote
 
 When it comes to writing the proposal, which you will submit to the GSoC application website, we offer some guidelines below:
 
-- **Proposal structure:** Please consult the [Blender GSoC application template](https://developer.blender.org/docs/programs/gsoc/application_template/) as reference for our desired format.
+- **Proposal structure:** Please consult the [Blender GSoC application template](https://developer.blender.org/docs/programs/gsoc/application_template/) as reference for our desired format. Remember: don't waste your—and our—time restating information that we already know, like background information about Graphite or the underlying technologies; we want to hear your thoughts and plans about what you uniquely bring to the table and how you will execute the project. It's not formal. And it will not be to your advantage to use an LLM to write your proposal.
 - **Your background:** We're especially interested in your background and experience, so attaching a résumé or CV is optional but highly recommended and will help us understand your capabilities. If able, please also include links to evidence of past open source contributions or personal projects in the bio section of your proposal. Our goal is to help you learn and grow as a productive open source software engineer, not to help you learn to program from scratch, so any such evidence will help us understand your potential as a self-motivated contributor to the open source community.
 - **Prior PRs:** If you have made any contributions to Graphite and/or similar open source projects, please include links to your pull requests in your proposal. We put significant extra weight towards applicants who have already made successful contributions to Graphite because this shows your ability to work in a professional capacity with our team and demonstrates your interest in Graphite in particular (as opposed to a shotgun approach to GSoC applications). You can also state that you'll submit your first PRs (we encourage at least two) after the application deadline on [April 2](https://developers.google.com/open-source/gsoc/timeline#april_2_-_1800_utc), but before we make our final selections a couple days prior to [April 24](https://developers.google.com/open-source/gsoc/timeline#april_24_-_1800_utc). We are very likely to reject applicants who have not made meaningful contributions to Graphite by that time.
 
@@ -63,7 +63,7 @@ This project involves diving into the LibRaw source code (~44,000 lines), unders
 
 The Graphite concept is built around a node graph representation of layer stacks, while tools automatically generate and manipulate nodes. When a layer or node is inserted, deleted, moved, or referenced, the graph needs to be reorganized to maintain a clear and useful layout. Users can also interactively expand and collapse groups of nodes which occupies or frees up graph real estate.
 
-Unlike other node editors that are centered around manual graph editing, where users are fully in charge of node placements within one large node network, Graphite's node UI is more oriented towards automatic layout management and viewing just parts of the graph at one time. This means the shown graph toplogy is constantly changing and the layout system needs to cooperatively organize the graph in concert with user actions.
+Unlike other node editors that are centered around manual graph editing, where users are fully in charge of node placements within one large node network, Graphite's node UI is more oriented towards automatic layout management and viewing just parts of the graph at one time. This means the shown graph topology is constantly changing and the layout system needs to cooperatively organize the graph in concert with user actions.
 
 While general graph layout algorithms are complex and struggle to produce good results in other node editors, Graphite's graph topology is more constrained and predictable, which makes it possible to design a layout system that can produce good results. Nodes tend to be organized into rows, and layers into columns (see the image in the project below). This turns the problem into more of a constraint-based, axis-aligned packing problem.
 
@@ -109,7 +109,7 @@ This is a key feature in Graphite's evolution to a fully-featured raster editor.
 
 AI is filling a rapidly growing role as a tool in the creative process. Graphite's procedural node-based workflow is uniquely suited to leveraging the power and flexibility of machine learning nodes.
 
-[Segment Anything](https://segment-anything.com/) (object segmentation), [Depth Anything](https://depth-anything.github.io/) (depth estimation), and [Stable Diffusion](https://github.com/CompVis/stable-diffusion) (image generation, generative fill, style transfer, etc.) are currently the three models we are most interested in integrating. The challenge is settling on an architecture and tech stack which is well suited for Graphite's requirements.
+[Segment Anything](https://segment-anything.com/) (object segmentation), [Depth Anything](https://depth-anything.github.io/) (depth estimation), and [Stable Diffusion](https://github.com/CompVis/stable-diffusion) (image generation, generative fill, style transfer, etc.) are currently the three models we are most [interested in integrating](https://github.com/GraphiteEditor/Graphite/issues/1694). The challenge is settling on an architecture and tech stack which is well suited for Graphite's requirements.
 
 The approach should be extensible to future models. It needs to run fast and natively on the assorted hardware of local user machines with hardware acceleration. It should be a one-click installation process for users to download and run models without requiring dependencies or environment setup. Ideally, it should allow the more lightweight models to run locally in browsers with WebGPU. It needs to also be deployable to servers in a scalable, cost-viable manner that reuses most of the same code that runs locally. Runtime overhead, cold start times, and memory usage should be minimized for quick, frequent switching between models in a node graph pipeline. The tech stack also needs to be permissively licensed and, as much as possible, Rust-centric so it doesn't add complexity to our Wasm and Tauri build processes. For Stable Diffusion, we need the flexability to track the latest research and extensions to the ecosystem like new base models, checkpoint training, DreamBooth, LoRA, ControlNet, IP-Adapter, etc. and expose these functionalities through modular nodes.
 
diff --git a/website/sass/base.scss b/website/sass/base.scss
index e823832f..415d032a 100644
--- a/website/sass/base.scss
+++ b/website/sass/base.scss
@@ -48,7 +48,7 @@
 		--border-thickness: 1px;
 	}
 
-	@media screen and (max-width: 500px) {
+	@media print, screen and (max-width: 500px) {
 		--font-size-intro-heading: 32px;
 		--font-size-intro-body: 16px;
 		--font-size-link: 16px;
@@ -151,47 +151,19 @@ p {
 	-webkit-hyphens: auto;
 	hyphens: auto;
 	text-align: justify;
-}
 
-p ~ img,
-p ~ iframe {
-	width: 100%;
-	height: auto;
-}
-
-p ~ p {
-	margin-top: 1.5em;
-}
-
-h1,
-h2,
-h3,
-h4 {
-	& ~ p,
-	& ~ ol li p,
-	& ~ img {
-		margin-top: 20px;
+	& ~ img,
+	& ~ iframe {
+		width: 100%;
+		height: auto;
 	}
 }
 
-h1 ~ .informational-group,
-p ~ h1,
-p ~ h2,
-p ~ h3,
-p ~ h4,
-p ~ details summary,
-p ~ blockquote,
-p ~ .informational-group,
-p ~ .image-comparison,
-p + .link,
-p + section,
-p + table,
-p + style + table,
-p ~ .video-background,
-p ~ .video-embed,
-.video-embed + p,
-.video-embed + .link,
-.video-embed + .button,
+:is(h1, h2, h3, h4, article > :first-child) ~ :is(p, ol li p, img),
+:is(h1, p) ~ .informational-group,
+p ~ :is(h1, h2, h3, h4, details summary, blockquote, .image-comparison, .video-background, .video-embed),
+.video-embed + :is(p, .link, .button),
+p + :is(.link, section),
 img + .link {
 	margin-top: 20px;
 }
@@ -213,18 +185,24 @@ li {
 	margin-top: 0.5em;
 }
 
+img {
+	vertical-align: top;
+}
+
 table {
-	margin: -20px;
+	margin: 20px -20px;
+	width: calc(100% + 40px);
 
 	th,
 	td {
+		border: 20px solid transparent;
+		vertical-align: top;
 		margin: 0;
 		padding: 0;
 	}
-	
-	td {
-		vertical-align: top;
-		border: 20px solid transparent;
+
+	th:empty {
+		border: none;
 	}
 }
 
@@ -352,8 +330,6 @@ pre {
 }
 
 kbd {
-	background: var(--color-fog);
-	border-radius: calc(var(--variable-px) * 2);
 	outline: calc(var(--border-thickness) / 2) solid var(--color-navy);
 	padding: 0 8px;
 	margin: 0 4px;
@@ -412,6 +388,11 @@ summary {
 				margin-top: 0;
 			}
 		}
+
+		// Captions below images in blog posts
+		p:has(> img) + center:has(> em) {
+			margin-top: 10px;
+		}
 	}
 }
 
@@ -1152,7 +1133,7 @@ body > .page {
 						}
 					}
 
-					@media screen and (max-width: 880px) {
+					@media print, screen and (max-width: 880px) {
 						gap: 20px;
 
 						a {
diff --git a/website/sass/book.scss b/website/sass/book.scss
index a56adba6..7c40131c 100644
--- a/website/sass/book.scss
+++ b/website/sass/book.scss
@@ -53,6 +53,12 @@
 		}
 	}
 
+	@media print {
+		aside {
+			display: none;
+		}
+	}
+
 	// Page contents right sidebar is removed on smaller screens
 	@media screen and (max-width: 1200px) {
 		.contents {