diff --git a/.changeset/add-hyperboards-lexicons.md b/.changeset/add-hyperboards-lexicons.md new file mode 100644 index 00000000..24a7b9e1 --- /dev/null +++ b/.changeset/add-hyperboards-lexicons.md @@ -0,0 +1,5 @@ +--- +"@hypercerts-org/lexicon": minor +--- + +Add `org.hyperboards.board` and `org.hyperboards.displayProfile` lexicons for hyperboard visual presentation records. diff --git a/SCHEMAS.md b/SCHEMAS.md index f521cfe6..679b1649 100644 --- a/SCHEMAS.md +++ b/SCHEMAS.md @@ -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 | @@ -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) diff --git a/lexicons/org/hyperboards/board.json b/lexicons/org/hyperboards/board.json new file mode 100644 index 00000000..32d5f408 --- /dev/null +++ b/lexicons/org/hyperboards/board.json @@ -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 + } + } + } + } +} diff --git a/lexicons/org/hyperboards/displayProfile.json b/lexicons/org/hyperboards/displayProfile.json new file mode 100644 index 00000000..d0af7f80 --- /dev/null +++ b/lexicons/org/hyperboards/displayProfile.json @@ -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." + } + } + } + } + } +} diff --git a/lexicons/org/hypercerts/defs.json b/lexicons/org/hypercerts/defs.json index 09993113..61ae443c 100644 --- a/lexicons/org/hypercerts/defs.json +++ b/lexicons/org/hypercerts/defs.json @@ -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"],