Skip to content

feat: add org.hyperboards.board and org.hyperboards.contributor lexicons #149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aspiers merged 8 commits into from
Mar 2, 2026
Merged

feat: add org.hyperboards.board and org.hyperboards.contributor lexicons #149

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
9f124eb
feat: add org.hyperboards.board and org.hyperboards.contributor lexicons
daviddao Feb 26, 2026
f7fc8cf
refactor: rename and improve hyperboards lexicons
holkexyz Feb 26, 2026
8395d15
refactor: make displayProfile a singleton with user-owned defaults
holkexyz Feb 26, 2026
60a82b7
feat: add smallVideo def and support video uploads in hyperboards
holkexyz Feb 27, 2026
de3ad35
refactor: rename config to board and improve contributor override naming
holkexyz Feb 27, 2026
a9028d9
refactor: remove isBlueprint from contributorOverride
holkexyz Feb 27, 2026
895b884
refactor: rename contributorOverrides to contributorDefaults
holkexyz Mar 1, 2026
fea8132
refactor: rename contributorDefault to contributorConfig
holkexyz Mar 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/add-hyperboards-lexicons.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@hypercerts-org/lexicon": minor
---

Add `org.hyperboards.board` and `org.hyperboards.displayProfile` lexicons for hyperboard visual presentation records.
73 changes: 73 additions & 0 deletions SCHEMAS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -468,6 +468,12 @@ Common type definitions used across all protocols.
| -------- | ------ | -------- | ----------------- |
| `image` | `blob` | ✅ | Image (up to 5MB) |

##### `org.hypercerts.defs#smallVideo`

| Property | Type | Required | Description |
| -------- | ------ | -------- | ------------------ |
| `video` | `blob` | ✅ | Video (up to 20MB) |

##### `org.hypercerts.defs#largeImage`

| Property | Type | Required | Description |
Expand All @@ -486,6 +492,73 @@ External lexicons from other protocols and systems.

---

### `org.hyperboards.board`

**Description:** Configuration record for a hyperboard, wrapping an underlying activity or collection with visual presentation settings. Stored in the creator's PDS.

**Key:** `tid`

#### Properties

| Property | Type | Required | Description | Comments |
| -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------- | --------------- |
| `subject` | `ref` | ✅ | Reference to the org.hypercerts.claim.activity or org.hypercerts.claim.collection this board visualizes. | |
| `config` | `ref` | ❌ | Visual configuration for a hyperboard's background, colors, and layout. | |
| `contributorConfigs` | `ref[]` | ❌ | Per-contributor configuration entries for this board. | maxLength: 1000 |
| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created. | |

#### Defs

##### `org.hyperboards.board#boardConfig`

| Property | Type | Required | Description |
| --------------------- | --------- | -------- | --------------------------------------------------------------------- |
| `backgroundType` | `string` | ❌ | Type of background content. |
| `backgroundImage` | `union` | ❌ | Background image as a URI or image blob. |
| `backgroundIframeUrl` | `string` | ❌ | URI of the background iframe. |
| `backgroundGrayscale` | `boolean` | ❌ | Whether the background is rendered in grayscale. Default: true. |
| `backgroundOpacity` | `integer` | ❌ | Background opacity as a percentage (0–100). |
| `backgroundColor` | `string` | ❌ | Background color as a hex string (e.g. '#ffffff'). |
| `borderColor` | `string` | ❌ | Border color as a hex string (e.g. '#000000'). |
| `grayscaleImages` | `boolean` | ❌ | Whether contributor images are rendered in grayscale. Default: false. |
| `imageShape` | `string` | ❌ | Shape used to crop contributor images on this board. |
| `aspectRatio` | `string` | ❌ | Display aspect ratio of the board. |

##### `org.hyperboards.board#contributorConfig`

| Property | Type | Required | Description |
| ---------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contributor` | `union` | ✅ | Identifies the contributor being styled. A strong reference to an org.hypercerts.claim.contributorInformation record, or a contributorIdentity (DID or identifier string) for contributors without a dedicated record. |
| `override` | `boolean` | ❌ | When true, these values take precedence over the contributor's own profile and display settings. When false or omitted, they are only used as fallbacks if the contributor has not set their own settings. |
| `displayName` | `string` | ❌ | Display name for this contributor on this board. |
| `image` | `union` | ❌ | Avatar or face image for this contributor on this board, as a URI or image blob. |
| `video` | `union` | ❌ | Video for this contributor, as a URI (embed/direct link) or uploaded video blob. |
| `hoverImage` | `union` | ❌ | Image overlay shown when hovering over this contributor, as a URI or image blob. |
| `hoverIframeUrl` | `string` | ❌ | Iframe overlay shown when hovering over this contributor. |
| `url` | `string` | ❌ | Click-through link URL for this contributor. |

---

### `org.hyperboards.displayProfile`

**Description:** User-declared visual presentation defaults for how a contributor appears on hyperboards. Stored in the contributor's own PDS and reusable across multiple boards.

**Key:** `literal:self`

#### Properties

| Property | Type | Required | Description | Comments |
| ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------------- | -------------------------------- |
| `displayName` | `string` | ❌ | Display name override for this user on hyperboards. | maxLength: 640, maxGraphemes: 64 |
| `image` | `union` | ❌ | Avatar or face image override for this user on hyperboards, as a URI or image blob. | |
| `video` | `union` | ❌ | Default video for this user across boards, as a URI (embed/direct link) or uploaded video blob. | |
| `hoverImage` | `union` | ❌ | Default hover image for this user across boards, as a URI or image blob. | |
| `hoverIframeUrl` | `string` | ❌ | Default hover iframe URL for this user across boards. | maxLength: 2048 |
| `url` | `string` | ❌ | Default click-through link URL for this user across boards. | maxLength: 2048 |
| `createdAt` | `string` | ✅ | Client-declared timestamp when this record was originally created. | |

---

## Notes

- All timestamps use the `datetime` format (ISO 8601)
Expand Down
152 changes: 152 additions & 0 deletions lexicons/org/hyperboards/board.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
{
"lexicon": 1,
"id": "org.hyperboards.board",
"defs": {
"main": {
"type": "record",
"description": "Configuration record for a hyperboard, wrapping an underlying activity or collection with visual presentation settings. Stored in the creator's PDS.",
"key": "tid",
"record": {
"type": "object",
"required": ["subject", "createdAt"],
"properties": {
"subject": {
"type": "ref",
"ref": "com.atproto.repo.strongRef",
"description": "Reference to the org.hypercerts.claim.activity or org.hypercerts.claim.collection this board visualizes."
},
"config": {
"type": "ref",
"ref": "#boardConfig",
"description": "Board-level visual configuration (background, colors, aspect ratio)."
},
"contributorConfigs": {
"type": "array",
"description": "Per-contributor configuration entries for this board.",
"maxLength": 1000,
"items": {
"type": "ref",
"ref": "#contributorConfig"
}
},
"createdAt": {
"type": "string",
"format": "datetime",
"description": "Client-declared timestamp when this record was originally created."
}
}
}
},
"boardConfig": {
"type": "object",
"description": "Visual configuration for a hyperboard's background, colors, and layout.",
"properties": {
"backgroundType": {
"type": "string",
"description": "Type of background content.",
"knownValues": ["image", "iframe"],
"maxLength": 10
},
"backgroundImage": {
"type": "union",
"refs": ["org.hypercerts.defs#uri", "org.hypercerts.defs#smallImage"],
"description": "Background image as a URI or image blob."
},
"backgroundIframeUrl": {
"type": "string",
"format": "uri",
"description": "URI of the background iframe.",
"maxLength": 2048
},
"backgroundGrayscale": {
"type": "boolean",
"description": "Whether the background is rendered in grayscale. Default: true."
},
"backgroundOpacity": {
"type": "integer",
"description": "Background opacity as a percentage (0–100).",
"minimum": 0,
"maximum": 100
},
"backgroundColor": {
"type": "string",
"description": "Background color as a hex string (e.g. '#ffffff').",
"maxLength": 20
},
"borderColor": {
"type": "string",
"description": "Border color as a hex string (e.g. '#000000').",
"maxLength": 20
},
"grayscaleImages": {
"type": "boolean",
"description": "Whether contributor images are rendered in grayscale. Default: false."
},
"imageShape": {
"type": "string",
"description": "Shape used to crop contributor images on this board.",
"knownValues": ["circular", "square"],
"maxLength": 20
},
"aspectRatio": {
"type": "string",
"description": "Display aspect ratio of the board.",
"knownValues": ["16:9", "4:3", "1:1"],
"maxLength": 10
}
}
},
"contributorConfig": {
"type": "object",
"description": "Configuration for a specific contributor within a board. Values serve as fallbacks when the contributor has not defined them on their profile. It can also be used to override contributor settings on this board without changing their global profile.",
"required": ["contributor"],
"properties": {
"contributor": {
"type": "union",
"refs": [
"com.atproto.repo.strongRef",
"org.hypercerts.claim.activity#contributorIdentity"
],
"description": "Identifies the contributor being styled. A strong reference to an org.hypercerts.claim.contributorInformation record, or a contributorIdentity (DID or identifier string) for contributors without a dedicated record."
},
"override": {
"type": "boolean",
"description": "When true, these values take precedence over the contributor's own profile and display settings. When false or omitted, they are only used as fallbacks if the contributor has not set their own settings."
},
"displayName": {
"type": "string",
"description": "Display name for this contributor on this board.",
"maxLength": 640,
"maxGraphemes": 64
},
"image": {
"type": "union",
"refs": ["org.hypercerts.defs#uri", "org.hypercerts.defs#smallImage"],
"description": "Avatar or face image for this contributor on this board, as a URI or image blob."
},
"video": {
"type": "union",
"refs": ["org.hypercerts.defs#uri", "org.hypercerts.defs#smallVideo"],
"description": "Video for this contributor, as a URI (embed/direct link) or uploaded video blob."
},
"hoverImage": {
"type": "union",
"refs": ["org.hypercerts.defs#uri", "org.hypercerts.defs#smallImage"],
"description": "Image overlay shown when hovering over this contributor, as a URI or image blob."
},
"hoverIframeUrl": {
"type": "string",
"format": "uri",
"description": "Iframe overlay shown when hovering over this contributor.",
"maxLength": 2048
},
"url": {
"type": "string",
"format": "uri",
"description": "Click-through link URL for this contributor.",
"maxLength": 2048
}
}
}
}
}
64 changes: 64 additions & 0 deletions lexicons/org/hyperboards/displayProfile.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
{
"lexicon": 1,
"id": "org.hyperboards.displayProfile",
"defs": {
"main": {
"type": "record",
"description": "User-declared visual presentation defaults for how a contributor appears on hyperboards. Stored in the contributor's own PDS and reusable across multiple boards.",
"key": "literal:self",
"record": {
"type": "object",
"required": ["createdAt"],
"properties": {
"displayName": {
"type": "string",
"description": "Display name override for this user on hyperboards.",
"maxLength": 640,
"maxGraphemes": 64
},
"image": {
"type": "union",
"refs": [
"org.hypercerts.defs#uri",
"org.hypercerts.defs#smallImage"
],
"description": "Avatar or face image override for this user on hyperboards, as a URI or image blob."
},
"video": {
"type": "union",
"refs": [
"org.hypercerts.defs#uri",
"org.hypercerts.defs#smallVideo"
],
"description": "Default video for this user across boards, as a URI (embed/direct link) or uploaded video blob."
},
"hoverImage": {
"type": "union",
"refs": [
"org.hypercerts.defs#uri",
"org.hypercerts.defs#smallImage"
],
"description": "Default hover image for this user across boards, as a URI or image blob."
},
"hoverIframeUrl": {
"type": "string",
"format": "uri",
"description": "Default hover iframe URL for this user across boards.",
"maxLength": 2048
},
"url": {
"type": "string",
"format": "uri",
"description": "Default click-through link URL for this user across boards.",
"maxLength": 2048
},
"createdAt": {
"type": "string",
"format": "datetime",
"description": "Client-declared timestamp when this record was originally created."
}
}
}
}
}
}
13 changes: 13 additions & 0 deletions lexicons/org/hypercerts/defs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,19 @@
}
}
},
"smallVideo": {
"type": "object",
"required": ["video"],
"description": "Object containing a small video",
"properties": {
"video": {
"type": "blob",
"accept": ["video/mp4", "video/webm"],
"maxSize": 20971520,
"description": "Video (up to 20MB)"
}
}
},
"largeImage": {
"type": "object",
"required": ["image"],
Expand Down