The Hypernote Design

Huge thank you to OpenSats for the grant to work on Hypernote this year! I thought I'd take this opportunity to try and share my thought processes for Hypernote. If this all sounds very dense or irrelevant to you I'm sorry!

===

How can the ideas of "hypermedia" benefit nostr? That's the goal of hypernote. To take the best ideas from "hypertext" and "hypercard" and "hypermedia systems" and apply them to nostr in a specifically nostr-ey way.

1. What do we mean by hypermedia

A hypermedia document embeds the methods of interaction (links, forms, and buttons are the most well-known hypermedia controls) within the document itself. It's including the how with the what.

This is how the old web worked. An HTML page was delivered to the web browser, and it included in it a link or perhaps a form that could be submitted to obtain a new, different HTML page. This is how the whole web worked early on! Forums and GeoCities and eBay and MySpace and Yahoo! and Amazon and Google all emerged inside this paradigm.

A web browser in this paradigm was a "thin" client which rendered the "thick" application defined in the HTML (and, implicitly, was defined by the server that would serve that HTML).

Contrast this with modern app development, where the what is usually delivered in the form of JSON, and then HTML combined with JavaScript (React, Svelte, Angular, Vue, etc.) is devised to render that JSON as a meaningful piece of hypermedia within the actual browser, the how.

The browser remains a "thin" client in this scenario, but now the application is delivered in two stages: a client application of HTML and JavaScript, and then the actual JSON data that will hydrate that "application".

(Aside: it's interesting how much "thicker" the browser has had to become to support this newer paradigm!)

Nostr was obviously built in line with the modern paradigm: nostr "clients" (written in React or Svelte or as mobile apps) define the how of reading and creating nostr events, while nostr events themselves (JSON data) simply describe the what.

And so the goal with Hypernote is to square this circle somehow: nostr currently delivers JSON what, how do we deliver the how with nostr as well. Is that even possible?

2. Hypernote's design assumptions

Hypernote assumes that hypermedia over nostr is a good idea! I'm expecting some joyful renaissance of app expression similar to that of the web once we figure out how to express applications in a truly "nostr" way.

Hypernote was also deeply inspired by HTMX, so it assumes that building web apps in the HTMX style is a good idea. The HTMX insight is that instead of shipping rich scripting along with your app, you could simply make HTML a tiny bit more expressive and get 95% of what most apps need. HTMX's additions to the HTML language are designed to be as minimal and composable as possible, and Hypernote should have the same aims.

Hypernote also assumes that the "design" of nostr will remain fluid and anarchic for years to come. There will be no "canonical" list of "required" NIPs that we'll have "consensus" on in order to build stable UIs on top of. Hypernote will need to be built responsive to nostr's moods and seasons, rather than one holy spec.

Hypernote likes the nak command line tool. Hypernote likes markdown. Hypernote likes Tailwind CSS. Hypernote likes SolidJS. Hypernote likes cold brew coffee. Hypernote is, to be perfectly honest, my aesthetic preferences applied to my perception of an opportunity in the nostr ecosystem.

3. "What's a hypernote?"

Great question. I'm still figuring this out. Everything right now is subject to change in order to make sure hypernote serves its intended purpose.

But here's where things currently stand:

A hypernote is a flat list of "Hypernote Elements". A Hypernote Element is composed of:

1. CONTENT. Static or dynamic content. (the what)
2. LOGIC. Filters and events (the how)
3. STYLE. Optional, inline style information specific to this element's content.

In the most basic example of a hypernote story, here's a lone "edit me" in the middle of the canvas:

{
	"id": "fb4aaed4-bf95-4353-a5e1-0bb64525c08f",
	"type": "text",
	"text": "edit me",
	"x": 540,
	"y": 960,
	"size": "md",
	"color": "black"
}

As you can see, it has no logic, but it does have some content (the text "edit me") and style (the position, size, and color).

Here's a "sticker" that displays a note:

{
    "id": "2cd1ef51-3356-408d-b10d-2502cbb8014e",
    "type": "sticker",
    "stickerType": "note",
    "filter": {
      "kinds": [
        1
      ],
      "ids": [
        "92de77507a361ab2e20385d98ff00565aaf3f80cf2b6d89c0343e08166fed931"
      ],
      "limit": 1
    },
    "accessors": [
      "content",
      "pubkey",
      "created_at"
    ],
    "x": 540,
    "y": 960,
    "associatedData": {}
  }

As you can see, it's kind of a mess! The content and styling and underdeveloped for this "sticker", but at least it demonstrates some "logic": a nostr filter for getting its data.

Here's another sticker, this one displays a form that the user can interact with to SEND a note. Very hyper of us!

{
    "id": "42240d75-e998-4067-b8fa-9ee096365663",
    "type": "sticker",
    "stickerType": "prompt",
    "filter": {},
    "accessors": [],
    "x": 540,
    "y": 960,
    "associatedData": {
      "promptText": "What's your favorite color?"
    },
    "methods": {
      "comment": {
        "description": "comment",
        "eventTemplate": {
          "kind": 1111,
          "content": "${content}",
          "tags": [
            [
              "E",
              "${eventId}",
              "",
              "${pubkey}"
            ],
            [
              "K",
              "${eventKind}"
            ],
            [
              "P",
              "${pubkey}"
            ],
            [
              "e",
              "${eventId}",
              "",
              "${pubkey}"
            ],
            [
              "k",
              "${eventKind}"
            ],
            [
              "p",
              "${pubkey}"
            ]
          ]
        }
      }
    }
  }

It's also a mess, but it demos the other part of "logic": methods which produce new events.

This is the total surface of hypernote, ideally! Static or dynamic content, simple inline styles, and logic for fetching and producing events.

I'm calling it "logic" but it's purposfully not a whole scripting language. At most we'll have some sort of jq-like language for destructing the relevant piece of data we want.

My ideal syntax for a hypernote as a developer will look something like

Nak-like logic

Markdown-like content

CSS-like styles

But with JSON as the compile target, this can just be my own preference, there can be other (likely better!) ways of authoring this content, such as a Hypernote Stories GUI.

The end

I know this is all still vague but I wanted to get some ideas out in the wild so people understand the through line of my different Hypernote experiments. I want to get the right amount of "expressivity" in Hypernote before it gets locked down into one spec. My hunch is it can be VERY expressive while remaining simple and also while not needing a whole scripting language bolted onto it. If I can't pull it off I'll let you know.