feat: add pub.leaflet lexicons

.changeset/add-pub-leaflet-lexicons.md

@@ -0,0 +1,5 @@
+---
+"@hypercerts-org/lexicon": minor
+---
+
+Vendor pub.leaflet and app.bsky.richtext.facet lexicon JSONs to enable runtime validation of records with description and facet fields. Previously, these external schemas were only shimmed at the TypeScript type level via @atcute packages, causing LexiconDefNotFoundError at runtime when validating records that populated optional description or facet fields. Removes the now-unnecessary create-shims.sh script and @atcute/leaflet + @atcute/bluesky dependencies.

AGENTS.md

@@ -97,9 +97,9 @@ npm run gen-api
 
 This runs `lex gen-api` on all lexicon JSON files and:
 
-1. Generates TypeScript types in `generated/`
-2. Creates type shims for external lexicons
-3. Auto-generates `generated/exports.ts` with clean exports
+1. Generates TypeScript types in `generated/` (including vendored
+   external lexicons from `lexicons/pub/` and `lexicons/app/bsky/`)
+2. Auto-generates `generated/exports.ts` with clean exports
 
 Then to build the distributable bundles:
 
@@ -231,8 +231,7 @@ scripts/                Build and codegen scripts
    structure
 
 2. Run `npm run gen-api` to:
-   - Generate types in `generated/`
-   - Create type shims for external lexicons
+   - Generate types in `generated/` (including vendored external lexicons)
    - Auto-generate `generated/exports.ts` with all exports
 
 3. Update `ERD.puml` as appropriate:

docs/AUTO_GENERATION.md

@@ -8,9 +8,8 @@ The `generated/exports.ts` file is **automatically generated** from lexicon JSON
 
 When you run `npm run gen-api`, the build process:
 
-1. Runs `lex gen-api` to generate TypeScript types in `generated/`
-2. Runs `scripts/create-shims.sh` to create type shims for external lexicons
-3. Runs `scripts/generate-exports.js` to auto-generate `generated/exports.ts`
+1. Runs `lex gen-api` to generate TypeScript types in `generated/` (including vendored external lexicons from `lexicons/pub/` and `lexicons/app/bsky/`)
+2. Runs `scripts/generate-exports.js` to auto-generate `generated/exports.ts`
 
 ## The Generation Script
 

lexicons/app/bsky/richtext/facet.json

@@ -0,0 +1,51 @@
+{
+  "lexicon": 1,
+  "id": "app.bsky.richtext.facet",
+  "defs": {
+    "main": {
+      "type": "object",
+      "description": "Annotation of a sub-string within rich text.",
+      "required": ["index", "features"],
+      "properties": {
+        "index": { "type": "ref", "ref": "#byteSlice" },
+        "features": {
+          "type": "array",
+          "items": { "type": "union", "refs": ["#mention", "#link", "#tag"] }
+        }
+      }
+    },
+    "mention": {
+      "type": "object",
+      "description": "Facet feature for mention of another account. The text is usually a handle, including a '@' prefix, but the facet reference is a DID.",
+      "required": ["did"],
+      "properties": {
+        "did": { "type": "string", "format": "did" }
+      }
+    },
+    "link": {
+      "type": "object",
+      "description": "Facet feature for a URL. The text URL may have been simplified or truncated, but the facet reference should be a complete URL.",
+      "required": ["uri"],
+      "properties": {
+        "uri": { "type": "string", "format": "uri" }
+      }
+    },
+    "tag": {
+      "type": "object",
+      "description": "Facet feature for a hashtag. The text usually includes a '#' prefix, but the facet reference should not (except in the case of 'double hash tags').",
+      "required": ["tag"],
+      "properties": {
+        "tag": { "type": "string", "maxLength": 640, "maxGraphemes": 64 }
+      }
+    },
+    "byteSlice": {
+      "type": "object",
+      "description": "Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets.",
+      "required": ["byteStart", "byteEnd"],
+      "properties": {
+        "byteStart": { "type": "integer", "minimum": 0 },
+        "byteEnd": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

lexicons/pub/leaflet/blocks/blockquote.json

@@ -0,0 +1,22 @@
+{
+  "lexicon": 1,
+  "id": "pub.leaflet.blocks.blockquote",
+  "defs": {
+    "main": {
+      "type": "object",
+      "required": ["plaintext"],
+      "properties": {
+        "plaintext": {
+          "type": "string"
+        },
+        "facets": {
+          "type": "array",
+          "items": {
+            "type": "ref",
+            "ref": "pub.leaflet.richtext.facet"
+          }
+        }
+      }
+    }
+  }
+}

lexicons/pub/leaflet/blocks/bskyPost.json

@@ -0,0 +1,19 @@
+{
+  "lexicon": 1,
+  "id": "pub.leaflet.blocks.bskyPost",
+  "defs": {
+    "main": {
+      "type": "object",
+      "required": ["postRef"],
+      "properties": {
+        "postRef": {
+          "type": "ref",
+          "ref": "com.atproto.repo.strongRef"
+        },
+        "clientHost": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

lexicons/pub/leaflet/blocks/button.json

@@ -0,0 +1,19 @@
+{
+  "lexicon": 1,
+  "id": "pub.leaflet.blocks.button",
+  "defs": {
+    "main": {
+      "type": "object",
+      "required": ["text", "url"],
+      "properties": {
+        "text": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri"
+        }
+      }
+    }
+  }
+}

lexicons/pub/leaflet/blocks/code.json

@@ -0,0 +1,21 @@
+{
+  "lexicon": 1,
+  "id": "pub.leaflet.blocks.code",
+  "defs": {
+    "main": {
+      "type": "object",
+      "required": ["plaintext"],
+      "properties": {
+        "plaintext": {
+          "type": "string"
+        },
+        "language": {
+          "type": "string"
+        },
+        "syntaxHighlightingTheme": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

lexicons/pub/leaflet/blocks/header.json

@@ -0,0 +1,27 @@
+{
+  "lexicon": 1,
+  "id": "pub.leaflet.blocks.header",
+  "defs": {
+    "main": {
+      "type": "object",
+      "required": ["plaintext"],
+      "properties": {
+        "level": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 6
+        },
+        "plaintext": {
+          "type": "string"
+        },
+        "facets": {
+          "type": "array",
+          "items": {
+            "type": "ref",
+            "ref": "pub.leaflet.richtext.facet"
+          }
+        }
+      }
+    }
+  }
+}

lexicons/pub/leaflet/blocks/horizontalRule.json

@@ -0,0 +1,11 @@
+{
+  "lexicon": 1,
+  "id": "pub.leaflet.blocks.horizontalRule",
+  "defs": {
+    "main": {
+      "type": "object",
+      "required": [],
+      "properties": {}
+    }
+  }
+}

lexicons/pub/leaflet/blocks/iframe.json

@@ -0,0 +1,21 @@
+{
+  "lexicon": 1,
+  "id": "pub.leaflet.blocks.iframe",
+  "defs": {
+    "main": {
+      "type": "object",
+      "required": ["url"],
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri"
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 16,
+          "maximum": 1600
+        }
+      }
+    }
+  }
+}

lexicons/pub/leaflet/blocks/image.json

@@ -0,0 +1,37 @@
+{
+  "lexicon": 1,
+  "id": "pub.leaflet.blocks.image",
+  "defs": {
+    "main": {
+      "type": "object",
+      "required": ["image", "aspectRatio"],
+      "properties": {
+        "image": {
+          "type": "blob",
+          "accept": ["image/*"],
+          "maxSize": 1000000
+        },
+        "alt": {
+          "type": "string",
+          "description": "Alt text description of the image, for accessibility."
+        },
+        "aspectRatio": {
+          "type": "ref",
+          "ref": "#aspectRatio"
+        }
+      }
+    },
+    "aspectRatio": {
+      "type": "object",
+      "required": ["width", "height"],
+      "properties": {
+        "width": {
+          "type": "integer"
+        },
+        "height": {
+          "type": "integer"
+        }
+      }
+    }
+  }
+}

lexicons/pub/leaflet/blocks/math.json

@@ -0,0 +1,15 @@
+{
+  "lexicon": 1,
+  "id": "pub.leaflet.blocks.math",
+  "defs": {
+    "main": {
+      "type": "object",
+      "required": ["tex"],
+      "properties": {
+        "tex": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

lexicons/pub/leaflet/blocks/orderedList.json

@@ -0,0 +1,54 @@
+{
+  "lexicon": 1,
+  "id": "pub.leaflet.blocks.orderedList",
+  "defs": {
+    "main": {
+      "type": "object",
+      "required": ["children"],
+      "properties": {
+        "startIndex": {
+          "type": "integer",
+          "description": "The starting number for this ordered list. Defaults to 1 if not specified."
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "type": "ref",
+            "ref": "#listItem"
+          }
+        }
+      }
+    },
+    "listItem": {
+      "type": "object",
+      "required": ["content"],
+      "properties": {
+        "checked": {
+          "type": "boolean",
+          "description": "If present, this item is a checklist item. true = checked, false = unchecked. If absent, this is a normal list item."
+        },
+        "content": {
+          "type": "union",
+          "refs": [
+            "pub.leaflet.blocks.text",
+            "pub.leaflet.blocks.header",
+            "pub.leaflet.blocks.image"
+          ]
+        },
+        "children": {
+          "type": "array",
+          "description": "Nested ordered list items. Mutually exclusive with unorderedListChildren; if both are present, children takes precedence.",
+          "items": {
+            "type": "ref",
+            "ref": "#listItem"
+          }
+        },
+        "unorderedListChildren": {
+          "type": "ref",
+          "description": "A nested unordered list. Mutually exclusive with children; if both are present, children takes precedence.",
+          "ref": "pub.leaflet.blocks.unorderedList"
+        }
+      }
+    }
+  }
+}

lexicons/pub/leaflet/blocks/page.json

@@ -0,0 +1,15 @@
+{
+  "lexicon": 1,
+  "id": "pub.leaflet.blocks.page",
+  "defs": {
+    "main": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

lexicons/pub/leaflet/blocks/poll.json

@@ -0,0 +1,16 @@
+{
+  "lexicon": 1,
+  "id": "pub.leaflet.blocks.poll",
+  "defs": {
+    "main": {
+      "type": "object",
+      "required": ["pollRef"],
+      "properties": {
+        "pollRef": {
+          "type": "ref",
+          "ref": "com.atproto.repo.strongRef"
+        }
+      }
+    }
+  }
+}