draft

83.md

@@ -0,0 +1,201 @@
+# NIP-83: Stories
+
+`draft` `optional`
+
+This NIP defines a standard for "stories" content.
+
+## Abstract
+
+Stories allow users to share, usually time-limited, visual content that can be enhanced with interactive elements called "stickers".
+
+## Specification
+
+### Event Structure
+
+Stories are represented as events with kind `23`.
+
+### Tags
+
+- `dim`: MUST be present, this is the story canvas in the format `["dim", "<width>x<height>"]`, which defines the coordinate system for all stickers and elements.
+- `imeta` tags as defined in NIP-92.
+- `dur` duration of the story in seconds.
+
+#### Sticker Tags
+
+Stickers are interactive elements placed on the story. They use the format:
+
+```
+["sticker", "<type>", "value", "<x>,<y>", "<width>x<height>", "key1 value1", "key2 value2", ...]
+```
+
+Where:
+
+- `<type>`: The sticker type (see below)
+- `<value>`: The main value of the sticker.
+- `<x>,<y>`: Position coordinates relative to the story canvas
+- `<width>x<height>`: Dimensions of the sticker
+- Additional key-value pairs with the key and value combined in a single element, separated by a space, like `imeta` tags.
+
+##### Sticker Types
+
+- `pubkey`: Mentions a user. Requires a `p` tag with the same index.
+- `event`: Embeds a Nostr event. Requires an `e` tag with the same index.
+- `prompt`: Requests user input with optional placeholder text.
+- `text`: Renders text on the story. The text content is specified using a `"text <value>"` property.
+- `countdown`: Displays a countdown timer to a specific Unix timestamp. The value should be a valid Unix timestamp in seconds.
+
+### Styling Properties
+
+Stickers can have additional properties:
+
+- `style`: A named style identifier. Clients are encouraged to mimic common style implementations from other clients.
+- `rot`: Rotation in degrees (0-360).
+
+Additional properties may be defined by clients, with common practices expected to emerge over time.
+
+## Design Considerations
+
+This NIP intentionally avoids highly specific styling mechanisms (like CSS) to ensure compatibility across different platforms, device types, and technologies. Instead, it provides foundational positioning and sizing with named styles that clients can interpret according to their capabilities.
+
+## Examples
+
+A basic story with an image and a text sticker:
+
+```json
+{
+  "kind": 23,
+  "content": "",
+  "tags": [
+    ["dim", "1080x1920"],
+    [
+      "imeta",
+      "url",
+      "https://example.com/image.jpg",
+      "m",
+      "image/jpeg",
+      "blurhash",
+      "UBL_:rOpGG-;0g9FD%IA4oIpELxu"
+    ],
+    [
+      "sticker",
+      "text",
+      "Hello Nostr!",
+      "540,960",
+      "600x200",
+      "style emphasis",
+      "rot 5"
+    ]
+  ]
+}
+```
+
+A story with a user mention:
+
+```json
+{
+  "kind": 23,
+  "content": "",
+  "tags": [
+    ["dim", "1080x1920"],
+    ["expiration", "<timestampp>"],
+    ["imeta", "url", "https://example.com/image.jpg", "m", "image/jpeg"],
+    ["p", "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"],
+    [
+      "sticker",
+      "pubkey",
+      "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52",
+      "540,960",
+      "300x300",
+      "style flou"
+    ],
+    [
+      "a",
+      "30023:6260f29fa75c91aaa292f082e5e87b438d2ab4fdf96af398567b01802ee2fcd4:7b734cf9"
+    ],
+    [
+      "sticker",
+      "event",
+      "30023:6260f29fa75c91aaa292f082e5e87b438d2ab4fdf96af398567b01802ee2fcd4:7b734cf9",
+      "540,960",
+      "300x300",
+      "style flou"
+    ]
+  ]
+}
+```
+
+A story with a countdown timer:
+
+```json
+{
+  "kind": 23,
+  "content": "",
+  "tags": [
+    ["expiration", "<timestamp>"],
+    ["dim", "1080x1920"],
+    ["imeta", "url", "https://example.com/event-image.jpg", "m", "image/jpeg"],
+    [
+      "sticker",
+      "countdown",
+      "1718486400",
+      "540,800",
+      "400x150",
+      "style emphasis",
+      "text Event starts in"
+    ]
+  ]
+}
+```
+
+## Client Behavior
+
+Clients SHOULD respect the coordinate system defined by the `dim` tag. When displaying stories on screens with different aspect ratios, clients SHOULD maintain the relative positioning of all elements.
+
+## Implementation Notes
+
+- Stories are ephemeral by nature. Clients MAY choose to display stories for a limited time (typically 24 hours).
+- For consistent rendering across platforms, measurements and coordinates SHOULD be treated as logical units rather than specific pixel values.
+- Clients SHOULD make reasonable attempts to reproduce named styles consistently with other implementations.
+
+## A note about `style`
+
+Stickers use a very ambiguous `style` with just a name. Clients can interpret what the name represents in their users screens freely, but clients should strive for consistency and sane defaults. Styles can emerge in the wild and clients are
+encouraged to work on supporting what their users want.
+
+The reason to avoid providing precise definitions and styling attributes is because recoinciling different platforms, native, web would end up yielding something as complicated as CSS which would be an overkill and, just like CSS has shown, an ever-shifting goal post.
+
+## Appendix 1: Sticker Type Examples
+
+### Mentions
+
+```
+["sticker", "pubkey", "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52", "540,960", "300x300", "style default"]
+```
+
+### Event
+
+An event to be embedded. Addressable events should use the `<kind>:<pubkey>:<d-tag>` format.
+
+Additionally, event stickers should include the corresponding `a` and/or `e` tag to help find the event (relay hint, etc.).
+
+```
+["sticker", "event", "1a5f6849cef16334e1a73f289d457d54833769731c0631a39ca9631a6575e91d", "200,500", "400x200", "style card"]
+```
+
+### Ask for a reply
+
+```
+["sticker", "prompt", "Ask me a question", "540,1200", "600x100", "style rounded"]
+```
+
+### Embed text
+
+```
+["sticker", "text", "Hello world!", "540,960", "500x150", "style bold", "rot 15"]
+```
+
+### Timer countdown
+
+```
+["sticker", "countdown", "1718486400", "540,700", "400x100", "text Event starts in"]
+```