Particles

Particles is a UI toolkit designed to answer the following question: "Now that LLMs can generate UI code, what's the right way to do this"? The word "right" is load bearing here and contains various intuitions and practices that guide the overall design -- aka "the Opinion".

Opinion

The following assertions comprise the guiding principles of the toolkit design:

• Sandbox the LLM -- Code that is generated by LLMs will have to be sandboxed to run safely. More specifically and as applies to the UI, code that drives UI:
  • must be able to do so asynchronously (though with minimal latency) from the code that renders UI;
  • must not be able to operate directly on the UI.
• Separate rendering from semantics -- The oldie-but-goodie from HTML, but now with feeling. Code that renders UI must have control in how UI is presented. Code that drives UI must be able to provide the semantics of what it's trying to convey, but not the exact rendering.
• Lean on signals -- it looks like signals are the future of Web UI, so might as well wholeheartedly adopt them.
• Prefer concrete use cases -- use the concrete use cases from implementations (like the Breadboard project) to inform priorities and overall shape of design. Theoretical explorations are great, but practical problems are better.

Overall Approach

Because the sandbox is the key design constraint, it figures prominently in the overall approach. Very loosely speaking, Particles splits the typical MVC setup into two layers:

• The Model + Controller, which is located inside of the sandbox
• The View, which is located outside of the sandbox.

The atomic unit is a Particle, representing a chunk of information to be presented in the UI. Each particle has semantics associated with it. Model + Controller produces particles and View consumes them.

Additionally, there's a Transport layer that handles the shuttling of particles between the Model+Controller and the View layers.

flowchart BT
    u["UI code"]
    v["View"]
    t["Transport"]
    mc["Model + Controller"]
    l["LLM-generated code"]
    subgraph Sandbox
      l -- "Calls to produce particles" --> mc
    end
    mc -- "Uses to send particles" --> t
    t -- "Provides received particles" --> v
    subgraph Outside of sandbox
      v -- "Presents signal-backed structure for rendering" --> u
    end

Loading

The communication also goes in the other direction (TBD).

Particle Types

Particles are meant to be very lightweight data structures.

There are three types of particle:

• Text particle represents text information of various types: HTML, markdown, plain text, JSON, etc.
• Data particle represents binary information, like media (audio/video/image) or anything that requires rendering-specific handling (PDF document, Google Drive file, etc.)
• Group particle represents a logical grouping of particles (think div).

Here are their type definitions:

type TextParticle = {
  /**
   * Content of the particle.
   */
  text: string;
  /**
   * The type of the content. If omitted, "text/markdown" is assumed.
   */
  mimeType?: string;
} 

type DataParticle = {
  /**
   * A URL that points to the data.
   */
  data: string;
  /**
   * The type of the data.
   */
  mimeType: string;
}

type GroupParticle = {
  /**
   * The sub-particles that are part of this group.
   */
  group: Map<ParticleIdentifier, Particle>;
  /**
   * The type of a group. Allows the particle to be bound to a particular
   * UI element. Optional. If not specified, the group particle doesn't have
   * an opinion about its type (think "generic grouping").
   */
  type?: string;
};

type Particle =
  | TextParticle
  | DataParticle
  | GroupParticle;

type ParticleIdentifier = string;