feature: atproto-extras crate

Cargo.lock

···
 ]
 
 [[package]]
+name = "atproto-extras"
+version = "0.13.0"
+dependencies = [
+ "anyhow",
+ "async-trait",
+ "atproto-identity",
+ "atproto-record",
+ "clap",
+ "regex",
+ "reqwest",
+ "serde_json",
+ "tokio",
+]
+
+[[package]]
 name = "atproto-identity"
 version = "0.13.0"
 dependencies = [
···
 checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
 dependencies = [
  "bitflags",
+]
+
+[[package]]
+name = "regex"
+version = "1.12.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843bc0191f75f3e22651ae5f1e72939ab2f72a4bc30fa80a066bd66edefc24d4"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
 ]
 
 [[package]]

Cargo.toml

···
 [workspace]
 members = [
     "crates/atproto-client",
+    "crates/atproto-extras",
     "crates/atproto-identity",
     "crates/atproto-jetstream",
     "crates/atproto-oauth-aip",
···
 categories = ["command-line-utilities", "web-programming"]
 
 [workspace.dependencies]
+atproto-attestation = { version = "0.13.0", path = "crates/atproto-attestation" }
 atproto-client = { version = "0.13.0", path = "crates/atproto-client" }
+atproto-extras = { version = "0.13.0", path = "crates/atproto-extras" }
 atproto-identity = { version = "0.13.0", path = "crates/atproto-identity" }
+atproto-jetstream = { version = "0.13.0", path = "crates/atproto-jetstream" }
 atproto-oauth = { version = "0.13.0", path = "crates/atproto-oauth" }
-atproto-oauth-axum = { version = "0.13.0", path = "crates/atproto-oauth-axum" }
 atproto-oauth-aip = { version = "0.13.0", path = "crates/atproto-oauth-aip" }
+atproto-oauth-axum = { version = "0.13.0", path = "crates/atproto-oauth-axum" }
 atproto-record = { version = "0.13.0", path = "crates/atproto-record" }
 atproto-xrpcs = { version = "0.13.0", path = "crates/atproto-xrpcs" }
-atproto-jetstream = { version = "0.13.0", path = "crates/atproto-jetstream" }
-atproto-attestation = { version = "0.13.0", path = "crates/atproto-attestation" }
 
+ammonia = "4.0"
 anyhow = "1.0"
 async-trait = "0.1"
 base64 = "0.22"
···
 p256 = "0.13"
 p384 = "0.13"
 rand = "0.8"
+regex = "1.11"
 reqwest = { version = "0.12", default-features = false, features = ["charset", "http2", "system-proxy", "json", "rustls-tls"] }
 reqwest-chain = "1.0"
 reqwest-middleware = { version = "0.4", features = ["json", "multipart"]}

crates/atproto-extras/Cargo.toml

···
+[package]
+name = "atproto-extras"
+version = "0.13.0"
+description = "AT Protocol extras - facet parsing and rich text utilities"
+readme = "README.md"
+homepage = "https://tangled.sh/@smokesignal.events/atproto-identity-rs"
+documentation = "https://docs.rs/atproto-extras"
+
+edition.workspace = true
+rust-version.workspace = true
+authors.workspace = true
+repository.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+atproto-identity.workspace = true
+atproto-record.workspace = true
+
+anyhow.workspace = true
+async-trait.workspace = true
+clap = { workspace = true, optional = true }
+regex.workspace = true
+reqwest = { workspace = true, optional = true }
+serde_json = { workspace = true, optional = true }
+tokio = { workspace = true, optional = true }
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["macros", "rt"] }
+
+[features]
+default = ["hickory-dns"]
+hickory-dns = ["atproto-identity/hickory-dns"]
+clap = ["dep:clap"]
+cli = ["dep:clap", "dep:serde_json", "dep:tokio", "dep:reqwest"]
+
+[[bin]]
+name = "atproto-extras-parse-facets"
+required-features = ["clap", "cli", "hickory-dns"]
+
+[lints]
+workspace = true

crates/atproto-extras/README.md

···
+# atproto-extras
+
+Extra utilities for AT Protocol applications, including rich text facet parsing.
+
+## Features
+
+- **Facet Parsing**: Extract mentions (`@handle`), URLs, and hashtags (`#tag`) from plain text with correct UTF-8 byte offset calculation
+- **Identity Integration**: Resolve mention handles to DIDs during parsing
+
+## Installation
+
+Add to your `Cargo.toml`:
+
+```toml
+[dependencies]
+atproto-extras = "0.13"
+```
+
+## Usage
+
+### Parsing Text for Facets
+
+```rust
+use atproto_extras::{parse_urls, parse_tags};
+use atproto_record::lexicon::app::bsky::richtext::facet::FacetFeature;
+
+let text = "Check out https://example.com #rust";
+
+// Parse URLs and tags - returns Vec<Facet> directly
+let url_facets = parse_urls(text);
+let tag_facets = parse_tags(text);
+
+// Each facet includes byte positions and typed features
+for facet in url_facets {
+    if let Some(FacetFeature::Link(link)) = facet.features.first() {
+        println!("URL at bytes {}..{}: {}",
+            facet.index.byte_start, facet.index.byte_end, link.uri);
+    }
+}
+
+for facet in tag_facets {
+    if let Some(FacetFeature::Tag(tag)) = facet.features.first() {
+        println!("Tag at bytes {}..{}: #{}",
+            facet.index.byte_start, facet.index.byte_end, tag.tag);
+    }
+}
+```
+
+### Parsing Mentions
+
+Mention parsing requires an `IdentityResolver` to convert handles to DIDs:
+
+```rust
+use atproto_extras::{parse_mentions, FacetLimits};
+use atproto_record::lexicon::app::bsky::richtext::facet::FacetFeature;
+
+let text = "Hello @alice.bsky.social!";
+let limits = FacetLimits::default();
+
+// Requires an async context and IdentityResolver
+let facets = parse_mentions(text, &resolver, &limits).await;
+
+for facet in facets {
+    if let Some(FacetFeature::Mention(mention)) = facet.features.first() {
+        println!("Mention at bytes {}..{} resolved to {}",
+            facet.index.byte_start, facet.index.byte_end, mention.did);
+    }
+}
+```
+
+Mentions that cannot be resolved to a valid DID are automatically skipped. Mentions appearing within URLs are also excluded.
+
+### Creating AT Protocol Facets
+
+```rust
+use atproto_extras::{parse_facets_from_text, FacetLimits};
+
+let text = "Hello @alice.bsky.social! Check https://rust-lang.org #rust";
+let limits = FacetLimits::default();
+
+// Requires an async context and IdentityResolver
+let facets = parse_facets_from_text(text, &resolver, &limits).await;
+
+if let Some(facets) = facets {
+    for facet in &facets {
+        println!("Facet at {}..{}", facet.index.byte_start, facet.index.byte_end);
+    }
+}
+```
+
+## Byte Offset Handling
+
+AT Protocol facets use UTF-8 byte offsets, not character indices. This is critical for correct handling of multi-byte characters like emojis or non-ASCII text.
+
+```rust
+use atproto_extras::parse_urls;
+
+// Text with emojis (multi-byte UTF-8 characters)
+let text = "✨ Check https://example.com ✨";
+
+let facets = parse_urls(text);
+// Byte positions correctly account for the 4-byte emoji
+assert_eq!(facets[0].index.byte_start, 11);  // After "✨ Check " (4 + 1 + 6 = 11 bytes)
+```
+
+## Facet Limits
+
+Use `FacetLimits` to control the maximum number of facets processed:
+
+```rust
+use atproto_extras::FacetLimits;
+
+// Default limits
+let limits = FacetLimits::default();
+// mentions_max: 5, tags_max: 5, links_max: 5, max: 10
+
+// Custom limits
+let custom = FacetLimits {
+    mentions_max: 10,
+    tags_max: 10,
+    links_max: 10,
+    max: 20,
+};
+```
+
+## License
+
+MIT

crates/atproto-extras/src/bin/atproto-extras-parse-facets.rs

···
+//! Command-line tool for generating AT Protocol facet arrays from text.
+//!
+//! This tool parses a string and outputs the facet array in JSON format.
+//! Facets include mentions (@handle), URLs (https://...), and hashtags (#tag).
+//!
+//! By default, mentions are detected but output with placeholder DIDs. Use
+//! `--resolve-mentions` to resolve handles to actual DIDs (requires network access).
+//!
+//! # Usage
+//!
+//! ```bash
+//! # Parse facets without resolving mentions
+//! cargo run --features clap,serde_json,tokio,hickory-dns --bin atproto-extras-parse-facets -- "Check out https://example.com and #rust"
+//!
+//! # Resolve mentions to DIDs
+//! cargo run --features clap,serde_json,tokio,hickory-dns --bin atproto-extras-parse-facets -- --resolve-mentions "Hello @bsky.app!"
+//! ```
+
+use atproto_extras::{FacetLimits, parse_mentions, parse_tags, parse_urls};
+use atproto_identity::resolve::{HickoryDnsResolver, InnerIdentityResolver};
+use atproto_record::lexicon::app::bsky::richtext::facet::{
+    ByteSlice, Facet, FacetFeature, Mention,
+};
+use clap::Parser;
+use regex::bytes::Regex;
+use std::sync::Arc;
+
+/// Parse text and output AT Protocol facets as JSON.
+#[derive(Parser)]
+#[command(
+    name = "atproto-extras-parse-facets",
+    version,
+    about = "Parse text and output AT Protocol facets as JSON",
+    long_about = "This tool parses a string for mentions, URLs, and hashtags,\n\
+                  then outputs the corresponding AT Protocol facet array in JSON format.\n\n\
+                  By default, mentions are detected but output with placeholder DIDs.\n\
+                  Use --resolve-mentions to resolve handles to actual DIDs (requires network)."
+)]
+struct Args {
+    /// The text to parse for facets
+    text: String,
+
+    /// Resolve mention handles to DIDs (requires network access)
+    #[arg(long)]
+    resolve_mentions: bool,
+
+    /// Show debug information on stderr
+    #[arg(long, short = 'd')]
+    debug: bool,
+}
+
+/// Parse mention spans from text without resolution (returns placeholder DIDs).
+fn parse_mention_spans(text: &str) -> Vec<Facet> {
+    let mut facets = Vec::new();
+
+    // Get URL ranges to exclude mentions within URLs
+    let url_facets = parse_urls(text);
+
+    // Same regex pattern as parse_mentions
+    let mention_regex = Regex::new(
+        r"(?:^|[^\w])(@([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)",
+    )
+    .expect("Invalid mention regex");
+
+    let text_bytes = text.as_bytes();
+
+    for capture in mention_regex.captures_iter(text_bytes) {
+        if let Some(mention_match) = capture.get(1) {
+            let start = mention_match.start();
+            let end = mention_match.end();
+
+            // Check if this mention overlaps with any URL
+            let overlaps_url = url_facets.iter().any(|facet| {
+                (start >= facet.index.byte_start && start < facet.index.byte_end)
+                    || (end > facet.index.byte_start && end <= facet.index.byte_end)
+            });
+
+            if !overlaps_url {
+                let handle = std::str::from_utf8(&mention_match.as_bytes()[1..])
+                    .unwrap_or_default()
+                    .to_string();
+
+                facets.push(Facet {
+                    index: ByteSlice {
+                        byte_start: start,
+                        byte_end: end,
+                    },
+                    features: vec![FacetFeature::Mention(Mention {
+                        did: format!("did:plc:<unresolved:{}>", handle),
+                    })],
+                });
+            }
+        }
+    }
+
+    facets
+}
+
+#[tokio::main]
+async fn main() {
+    let args = Args::parse();
+    let text = &args.text;
+    let mut facets: Vec<Facet> = Vec::new();
+    let limits = FacetLimits::default();
+
+    // Parse mentions (either resolved or with placeholders)
+    if args.resolve_mentions {
+        let http_client = reqwest::Client::new();
+        let dns_resolver = HickoryDnsResolver::create_resolver(&[]);
+        let resolver = InnerIdentityResolver {
+            http_client,
+            dns_resolver: Arc::new(dns_resolver),
+            plc_hostname: "plc.directory".to_string(),
+        };
+        let mention_facets = parse_mentions(text, &resolver, &limits).await;
+        facets.extend(mention_facets);
+    } else {
+        let mention_facets = parse_mention_spans(text);
+        facets.extend(mention_facets);
+    }
+
+    // Parse URLs
+    let url_facets = parse_urls(text);
+    facets.extend(url_facets);
+
+    // Parse hashtags
+    let tag_facets = parse_tags(text);
+    facets.extend(tag_facets);
+
+    // Sort facets by byte_start for consistent output
+    facets.sort_by_key(|f| f.index.byte_start);
+
+    // Output as JSON
+    if facets.is_empty() {
+        println!("null");
+    } else {
+        match serde_json::to_string_pretty(&facets) {
+            Ok(json) => println!("{}", json),
+            Err(e) => {
+                eprintln!(
+                    "error-atproto-extras-parse-facets-1 Error serializing facets: {}",
+                    e
+                );
+                std::process::exit(1);
+            }
+        }
+    }
+
+    // Show debug info if requested
+    if args.debug {
+        eprintln!();
+        eprintln!("--- Debug Info ---");
+        eprintln!("Input text: {:?}", text);
+        eprintln!("Text length: {} bytes", text.len());
+        eprintln!("Facets found: {}", facets.len());
+        eprintln!("Mentions resolved: {}", args.resolve_mentions);
+
+        // Show byte slice verification
+        let text_bytes = text.as_bytes();
+        for (i, facet) in facets.iter().enumerate() {
+            let start = facet.index.byte_start;
+            let end = facet.index.byte_end;
+            let slice_text =
+                std::str::from_utf8(&text_bytes[start..end]).unwrap_or("<invalid utf8>");
+            let feature_type = match &facet.features[0] {
+                FacetFeature::Mention(_) => "mention",
+                FacetFeature::Link(_) => "link",
+                FacetFeature::Tag(_) => "tag",
+            };
+            eprintln!(
+                "  [{}] {} @ bytes {}..{}: {:?}",
+                i, feature_type, start, end, slice_text
+            );
+        }
+    }
+}

crates/atproto-extras/src/facets.rs

···
+//! Rich text facet parsing for AT Protocol.
+//!
+//! This module provides functionality for extracting semantic annotations (facets)
+//! from plain text. Facets include mentions, links (URLs), and hashtags.
+//!
+//! # Overview
+//!
+//! AT Protocol rich text uses "facets" to annotate specific byte ranges within text with
+//! semantic meaning. This module handles:
+//!
+//! - **Parsing**: Extract mentions, URLs, and hashtags from plain text
+//! - **Facet Creation**: Build proper AT Protocol facet structures with resolved DIDs
+//!
+//! # Byte Offset Calculation
+//!
+//! This implementation correctly uses UTF-8 byte offsets as required by AT Protocol.
+//! The facets use "inclusive start and exclusive end" byte ranges. All parsing is done
+//! using `regex::bytes::Regex` which operates on byte slices and returns byte positions,
+//! ensuring correct handling of multi-byte UTF-8 characters (emojis, CJK, accented chars).
+//!
+//! # Example
+//!
+//! ```ignore
+//! use atproto_extras::facets::{parse_urls, parse_tags, FacetLimits};
+//! use atproto_record::lexicon::app::bsky::richtext::facet::FacetFeature;
+//!
+//! let text = "Check out https://example.com #rust";
+//!
+//! // Parse URLs and tags as Facet objects
+//! let url_facets = parse_urls(text);
+//! let tag_facets = parse_tags(text);
+//!
+//! // Access facet data directly
+//! for facet in url_facets {
+//!     if let Some(FacetFeature::Link(link)) = facet.features.first() {
+//!         println!("URL at bytes {}..{}: {}",
+//!             facet.index.byte_start, facet.index.byte_end, link.uri);
+//!     }
+//! }
+//! ```
+
+use atproto_identity::resolve::IdentityResolver;
+use atproto_record::lexicon::app::bsky::richtext::facet::{
+    ByteSlice, Facet, FacetFeature, Link, Mention, Tag,
+};
+use regex::bytes::Regex;
+
+/// Configuration for facet parsing limits.
+///
+/// These limits protect against abuse by capping the number of facets
+/// that will be processed. This is important for both performance and
+/// security when handling user-generated content.
+///
+/// # Example
+///
+/// ```
+/// use atproto_extras::FacetLimits;
+///
+/// // Use defaults
+/// let limits = FacetLimits::default();
+///
+/// // Or customize
+/// let custom = FacetLimits {
+///     mentions_max: 10,
+///     tags_max: 10,
+///     links_max: 10,
+///     max: 20,
+/// };
+/// ```
+#[derive(Debug, Clone, Copy)]
+pub struct FacetLimits {
+    /// Maximum number of mention facets to process (default: 5)
+    pub mentions_max: usize,
+    /// Maximum number of tag facets to process (default: 5)
+    pub tags_max: usize,
+    /// Maximum number of link facets to process (default: 5)
+    pub links_max: usize,
+    /// Maximum total number of facets to process (default: 10)
+    pub max: usize,
+}
+
+impl Default for FacetLimits {
+    fn default() -> Self {
+        Self {
+            mentions_max: 5,
+            tags_max: 5,
+            links_max: 5,
+            max: 10,
+        }
+    }
+}
+
+/// Parse mentions from text and return them as Facet objects with resolved DIDs.
+///
+/// This function extracts AT Protocol handle mentions (e.g., `@alice.bsky.social`)
+/// from text, resolves each handle to a DID using the provided identity resolver,
+/// and returns AT Protocol Facet objects with Mention features.
+///
+/// Mentions that cannot be resolved to a valid DID are skipped. Mentions that
+/// appear within URLs are also excluded to avoid false positives.
+///
+/// # Arguments
+///
+/// * `text` - The text to parse for mentions
+/// * `identity_resolver` - Resolver for converting handles to DIDs
+/// * `limits` - Configuration for maximum mentions to process
+///
+/// # Returns
+///
+/// A vector of Facet objects for successfully resolved mentions.
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_extras::{parse_mentions, FacetLimits};
+/// use atproto_record::lexicon::app::bsky::richtext::facet::FacetFeature;
+///
+/// let text = "Hello @alice.bsky.social!";
+/// let limits = FacetLimits::default();
+///
+/// // Requires an async context and identity resolver
+/// let facets = parse_mentions(text, &resolver, &limits).await;
+///
+/// for facet in facets {
+///     if let Some(FacetFeature::Mention(mention)) = facet.features.first() {
+///         println!("Mention {} resolved to {}",
+///             &text[facet.index.byte_start..facet.index.byte_end],
+///             mention.did);
+///     }
+/// }
+/// ```
+pub async fn parse_mentions(
+    text: &str,
+    identity_resolver: &dyn IdentityResolver,
+    limits: &FacetLimits,
+) -> Vec<Facet> {
+    let mut facets = Vec::new();
+
+    // First, parse all URLs to exclude mention matches within them
+    let url_facets = parse_urls(text);
+
+    // Regex based on: https://atproto.com/specs/handle#handle-identifier-syntax
+    // Pattern: [$|\W](@([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)
+    let mention_regex = Regex::new(
+        r"(?:^|[^\w])(@([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)",
+    )
+    .unwrap();
+
+    let text_bytes = text.as_bytes();
+    let mut mention_count = 0;
+
+    for capture in mention_regex.captures_iter(text_bytes) {
+        if mention_count >= limits.mentions_max {
+            break;
+        }
+
+        if let Some(mention_match) = capture.get(1) {
+            let start = mention_match.start();
+            let end = mention_match.end();
+
+            // Check if this mention overlaps with any URL
+            let overlaps_url = url_facets.iter().any(|facet| {
+                // Check if mention is within or overlaps the URL span
+                (start >= facet.index.byte_start && start < facet.index.byte_end)
+                    || (end > facet.index.byte_start && end <= facet.index.byte_end)
+            });
+
+            // Only process the mention if it doesn't overlap with a URL
+            if !overlaps_url {
+                let handle = std::str::from_utf8(&mention_match.as_bytes()[1..])
+                    .unwrap_or_default()
+                    .to_string();
+
+                // Try to resolve the handle to a DID
+                // First try with at:// prefix, then without
+                let at_uri = format!("at://{}", handle);
+                let did_result = match identity_resolver.resolve(&at_uri).await {
+                    Ok(doc) => Ok(doc),
+                    Err(_) => identity_resolver.resolve(&handle).await,
+                };
+
+                // Only add the mention facet if we successfully resolved the DID
+                if let Ok(did_doc) = did_result {
+                    facets.push(Facet {
+                        index: ByteSlice {
+                            byte_start: start,
+                            byte_end: end,
+                        },
+                        features: vec![FacetFeature::Mention(Mention {
+                            did: did_doc.id.to_string(),
+                        })],
+                    });
+                    mention_count += 1;
+                }
+            }
+        }
+    }
+
+    facets
+}
+
+/// Parse URLs from text and return them as Facet objects.
+///
+/// This function extracts HTTP and HTTPS URLs from text with correct
+/// byte position tracking for UTF-8 text, returning AT Protocol Facet objects
+/// with Link features.
+///
+/// # Supported URL Patterns
+///
+/// - HTTP URLs: `http://example.com`
+/// - HTTPS URLs: `https://example.com`
+/// - URLs with paths, query strings, and fragments
+/// - URLs with subdomains: `https://www.example.com`
+///
+/// # Example
+///
+/// ```
+/// use atproto_extras::parse_urls;
+/// use atproto_record::lexicon::app::bsky::richtext::facet::FacetFeature;
+///
+/// let text = "Visit https://example.com/path?query=1 for more info";
+/// let facets = parse_urls(text);
+///
+/// assert_eq!(facets.len(), 1);
+/// assert_eq!(facets[0].index.byte_start, 6);
+/// assert_eq!(facets[0].index.byte_end, 38);
+/// if let Some(FacetFeature::Link(link)) = facets[0].features.first() {
+///     assert_eq!(link.uri, "https://example.com/path?query=1");
+/// }
+/// ```
+///
+/// # Multi-byte Character Handling
+///
+/// Byte positions are correctly calculated even with emojis and other
+/// multi-byte UTF-8 characters:
+///
+/// ```
+/// use atproto_extras::parse_urls;
+/// use atproto_record::lexicon::app::bsky::richtext::facet::FacetFeature;
+///
+/// let text = "Check out https://example.com now!";
+/// let facets = parse_urls(text);
+/// let text_bytes = text.as_bytes();
+///
+/// // The byte slice matches the URL
+/// let url_bytes = &text_bytes[facets[0].index.byte_start..facets[0].index.byte_end];
+/// assert_eq!(std::str::from_utf8(url_bytes).unwrap(), "https://example.com");
+/// ```
+pub fn parse_urls(text: &str) -> Vec<Facet> {
+    let mut facets = Vec::new();
+
+    // Partial/naive URL regex based on: https://stackoverflow.com/a/3809435
+    // Pattern: [$|\W](https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]+\b([-a-zA-Z0-9()@:%_\+.~#?&//=]*[-a-zA-Z0-9@%_\+~#//=])?)
+    // Modified to use + instead of {1,6} to support longer TLDs and multi-level subdomains
+    let url_regex = Regex::new(
+        r"(?:^|[^\w])(https?://(?:www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]+\b(?:[-a-zA-Z0-9()@:%_\+.~#?&//=]*[-a-zA-Z0-9@%_\+~#//=])?)"
+    ).unwrap();
+
+    let text_bytes = text.as_bytes();
+    for capture in url_regex.captures_iter(text_bytes) {
+        if let Some(url_match) = capture.get(1) {
+            let url = std::str::from_utf8(url_match.as_bytes())
+                .unwrap_or_default()
+                .to_string();
+
+            facets.push(Facet {
+                index: ByteSlice {
+                    byte_start: url_match.start(),
+                    byte_end: url_match.end(),
+                },
+                features: vec![FacetFeature::Link(Link { uri: url })],
+            });
+        }
+    }
+
+    facets
+}
+
+/// Parse hashtags from text and return them as Facet objects.
+///
+/// This function extracts hashtags (e.g., `#rust`, `#ATProto`) from text,
+/// returning AT Protocol Facet objects with Tag features.
+/// It supports both standard `#` and full-width `＃` (U+FF03) hash symbols.
+///
+/// # Tag Syntax
+///
+/// - Tags must start with `#` or `＃` (full-width)
+/// - Tag content follows word character rules (`\w`)
+/// - Purely numeric tags (e.g., `#123`) are excluded
+///
+/// # Example
+///
+/// ```
+/// use atproto_extras::parse_tags;
+/// use atproto_record::lexicon::app::bsky::richtext::facet::FacetFeature;
+///
+/// let text = "Learning #rust and #golang today! #100DaysOfCode";
+/// let facets = parse_tags(text);
+///
+/// assert_eq!(facets.len(), 3);
+/// if let Some(FacetFeature::Tag(tag)) = facets[0].features.first() {
+///     assert_eq!(tag.tag, "rust");
+/// }
+/// if let Some(FacetFeature::Tag(tag)) = facets[1].features.first() {
+///     assert_eq!(tag.tag, "golang");
+/// }
+/// if let Some(FacetFeature::Tag(tag)) = facets[2].features.first() {
+///     assert_eq!(tag.tag, "100DaysOfCode");
+/// }
+/// ```
+///
+/// # Numeric Tags
+///
+/// Purely numeric tags are excluded:
+///
+/// ```
+/// use atproto_extras::parse_tags;
+///
+/// let text = "Item #42 is special";
+/// let facets = parse_tags(text);
+///
+/// // #42 is not extracted because it's purely numeric
+/// assert_eq!(facets.len(), 0);
+/// ```
+pub fn parse_tags(text: &str) -> Vec<Facet> {
+    let mut facets = Vec::new();
+
+    // Regex based on: https://github.com/bluesky-social/atproto/blob/d91988fe79030b61b556dd6f16a46f0c3b9d0b44/packages/api/src/rich-text/util.ts
+    // Simplified for Rust - matches hashtags at word boundaries
+    // Pattern matches: start of string or non-word char, then # or ＃, then tag content
+    let tag_regex = Regex::new(r"(?:^|[^\w])([#\xEF\xBC\x83])([\w]+(?:[\w]*)*)").unwrap();
+
+    let text_bytes = text.as_bytes();
+
+    // Work with bytes for proper position tracking
+    for capture in tag_regex.captures_iter(text_bytes) {
+        if let (Some(full_match), Some(hash_match), Some(tag_match)) =
+            (capture.get(0), capture.get(1), capture.get(2))
+        {
+            // Calculate the absolute byte position of the hash symbol
+            // The full match includes the preceding character (if any)
+            // so we need to adjust for that
+            let match_start = full_match.start();
+            let hash_offset = hash_match.start() - full_match.start();
+            let start = match_start + hash_offset;
+            let end = match_start + hash_offset + hash_match.len() + tag_match.len();
+
+            // Extract just the tag text (without the hash symbol)
+            let tag = std::str::from_utf8(tag_match.as_bytes()).unwrap_or_default();
+
+            // Only include tags that are not purely numeric
+            if !tag.chars().all(|c| c.is_ascii_digit()) {
+                facets.push(Facet {
+                    index: ByteSlice {
+                        byte_start: start,
+                        byte_end: end,
+                    },
+                    features: vec![FacetFeature::Tag(Tag {
+                        tag: tag.to_string(),
+                    })],
+                });
+            }
+        }
+    }
+
+    facets
+}
+
+/// Parse facets from text and return a vector of Facet objects.
+///
+/// This function extracts mentions, URLs, and hashtags from the provided text
+/// and creates AT Protocol facets with proper byte indices.
+///
+/// Mentions are resolved to actual DIDs using the provided identity resolver.
+/// If a handle cannot be resolved to a DID, the mention facet is skipped.
+///
+/// # Arguments
+///
+/// * `text` - The text to extract facets from
+/// * `identity_resolver` - Resolver for converting handles to DIDs
+/// * `limits` - Configuration for maximum facets per type and total
+///
+/// # Returns
+///
+/// Optional vector of facets. Returns `None` if no facets were found.
+///
+/// # Example
+///
+/// ```ignore
+/// use atproto_extras::{parse_facets_from_text, FacetLimits};
+///
+/// let text = "Hello @alice.bsky.social! Check #rust at https://rust-lang.org";
+/// let limits = FacetLimits::default();
+///
+/// // Requires an async context and identity resolver
+/// let facets = parse_facets_from_text(text, &resolver, &limits).await;
+///
+/// if let Some(facets) = facets {
+///     for facet in &facets {
+///         println!("Facet at {}..{}", facet.index.byte_start, facet.index.byte_end);
+///     }
+/// }
+/// ```
+///
+/// # Mention Resolution
+///
+/// Mentions are only included if the handle resolves to a valid DID:
+///
+/// ```ignore
+/// let text = "@valid.handle.com and @invalid.handle.xyz";
+/// let facets = parse_facets_from_text(text, &resolver, &limits).await;
+///
+/// // Only @valid.handle.com appears as a facet if @invalid.handle.xyz
+/// // cannot be resolved to a DID
+/// ```
+pub async fn parse_facets_from_text(
+    text: &str,
+    identity_resolver: &dyn IdentityResolver,
+    limits: &FacetLimits,
+) -> Option<Vec<Facet>> {
+    let mut facets = Vec::new();
+
+    // Parse mentions (already limited by mentions_max in parse_mentions)
+    let mention_facets = parse_mentions(text, identity_resolver, limits).await;
+    facets.extend(mention_facets);
+
+    // Parse URLs (limited by links_max)
+    let url_facets = parse_urls(text);
+    for (idx, facet) in url_facets.into_iter().enumerate() {
+        if idx >= limits.links_max {
+            break;
+        }
+        facets.push(facet);
+    }
+
+    // Parse hashtags (limited by tags_max)
+    let tag_facets = parse_tags(text);
+    for (idx, facet) in tag_facets.into_iter().enumerate() {
+        if idx >= limits.tags_max {
+            break;
+        }
+        facets.push(facet);
+    }
+
+    // Apply global facet limit (truncate if exceeds max)
+    if facets.len() > limits.max {
+        facets.truncate(limits.max);
+    }
+
+    // Only return facets if we found any
+    if !facets.is_empty() {
+        Some(facets)
+    } else {
+        None
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use async_trait::async_trait;
+    use atproto_identity::model::Document;
+    use std::collections::HashMap;
+
+    use super::*;
+
+    /// Mock identity resolver for testing
+    struct MockIdentityResolver {
+        handles_to_dids: HashMap<String, String>,
+    }
+
+    impl MockIdentityResolver {
+        fn new() -> Self {
+            let mut handles_to_dids = HashMap::new();
+            handles_to_dids.insert(
+                "alice.bsky.social".to_string(),
+                "did:plc:alice123".to_string(),
+            );
+            handles_to_dids.insert(
+                "at://alice.bsky.social".to_string(),
+                "did:plc:alice123".to_string(),
+            );
+            Self { handles_to_dids }
+        }
+
+        fn add_identity(&mut self, handle: &str, did: &str) {
+            self.handles_to_dids
+                .insert(handle.to_string(), did.to_string());
+            self.handles_to_dids
+                .insert(format!("at://{}", handle), did.to_string());
+        }
+    }
+
+    #[async_trait]
+    impl IdentityResolver for MockIdentityResolver {
+        async fn resolve(&self, handle: &str) -> anyhow::Result<Document> {
+            let handle_key = handle.to_string();
+
+            if let Some(did) = self.handles_to_dids.get(&handle_key) {
+                Ok(Document {
+                    context: vec![],
+                    id: did.clone(),
+                    also_known_as: vec![format!("at://{}", handle_key.trim_start_matches("at://"))],
+                    verification_method: vec![],
+                    service: vec![],
+                    extra: HashMap::new(),
+                })
+            } else {
+                Err(anyhow::anyhow!("Handle not found"))
+            }
+        }
+    }
+
+    #[tokio::test]
+    async fn test_parse_facets_from_text_comprehensive() {
+        let mut resolver = MockIdentityResolver::new();
+        resolver.add_identity("bob.test.com", "did:plc:bob456");
+
+        let limits = FacetLimits::default();
+        let text = "Join @alice.bsky.social and @bob.test.com at https://example.com #rust #golang";
+        let facets = parse_facets_from_text(text, &resolver, &limits).await;
+
+        assert!(facets.is_some());
+        let facets = facets.unwrap();
+        assert_eq!(facets.len(), 5); // 2 mentions, 1 URL, 2 hashtags
+
+        // Check first mention
+        assert_eq!(facets[0].index.byte_start, 5);
+        assert_eq!(facets[0].index.byte_end, 23);
+        if let FacetFeature::Mention(ref mention) = facets[0].features[0] {
+            assert_eq!(mention.did, "did:plc:alice123");
+        } else {
+            panic!("Expected Mention feature");
+        }
+
+        // Check second mention
+        assert_eq!(facets[1].index.byte_start, 28);
+        assert_eq!(facets[1].index.byte_end, 41);
+        if let FacetFeature::Mention(mention) = &facets[1].features[0] {
+            assert_eq!(mention.did, "did:plc:bob456");
+        } else {
+            panic!("Expected Mention feature");
+        }
+
+        // Check URL
+        assert_eq!(facets[2].index.byte_start, 45);
+        assert_eq!(facets[2].index.byte_end, 64);
+        if let FacetFeature::Link(link) = &facets[2].features[0] {
+            assert_eq!(link.uri, "https://example.com");
+        } else {
+            panic!("Expected Link feature");
+        }
+
+        // Check first hashtag
+        assert_eq!(facets[3].index.byte_start, 65);
+        assert_eq!(facets[3].index.byte_end, 70);
+        if let FacetFeature::Tag(tag) = &facets[3].features[0] {
+            assert_eq!(tag.tag, "rust");
+        } else {
+            panic!("Expected Tag feature");
+        }
+
+        // Check second hashtag
+        assert_eq!(facets[4].index.byte_start, 71);
+        assert_eq!(facets[4].index.byte_end, 78);
+        if let FacetFeature::Tag(tag) = &facets[4].features[0] {
+            assert_eq!(tag.tag, "golang");
+        } else {
+            panic!("Expected Tag feature");
+        }
+    }
+
+    #[tokio::test]
+    async fn test_parse_facets_from_text_with_unresolvable_mention() {
+        let resolver = MockIdentityResolver::new();
+        let limits = FacetLimits::default();
+
+        // Only alice.bsky.social is in the resolver, not unknown.handle.com
+        let text = "Contact @unknown.handle.com for details #rust";
+        let facets = parse_facets_from_text(text, &resolver, &limits).await;
+
+        assert!(facets.is_some());
+        let facets = facets.unwrap();
+        // Should only have 1 facet (the hashtag) since the mention couldn't be resolved
+        assert_eq!(facets.len(), 1);
+
+        // Check that it's the hashtag facet
+        if let FacetFeature::Tag(tag) = &facets[0].features[0] {
+            assert_eq!(tag.tag, "rust");
+        } else {
+            panic!("Expected Tag feature");
+        }
+    }
+
+    #[tokio::test]
+    async fn test_parse_facets_from_text_empty() {
+        let resolver = MockIdentityResolver::new();
+        let limits = FacetLimits::default();
+        let text = "No mentions, URLs, or hashtags here";
+        let facets = parse_facets_from_text(text, &resolver, &limits).await;
+        assert!(facets.is_none());
+    }
+
+    #[tokio::test]
+    async fn test_parse_facets_from_text_url_with_at_mention() {
+        let resolver = MockIdentityResolver::new();
+        let limits = FacetLimits::default();
+
+        // URLs with @ should not create mention facets
+        let text = "Tangled https://tangled.org/@smokesignal.events";
+        let facets = parse_facets_from_text(text, &resolver, &limits).await;
+
+        assert!(facets.is_some());
+        let facets = facets.unwrap();
+
+        // Should have exactly 1 facet (the URL), not 2 (URL + mention)
+        assert_eq!(
+            facets.len(),
+            1,
+            "Expected 1 facet (URL only), got {}",
+            facets.len()
+        );
+
+        // Verify it's a link facet, not a mention
+        if let FacetFeature::Link(link) = &facets[0].features[0] {
+            assert_eq!(link.uri, "https://tangled.org/@smokesignal.events");
+        } else {
+            panic!("Expected Link feature, got Mention or Tag instead");
+        }
+    }
+
+    #[tokio::test]
+    async fn test_parse_facets_with_mention_limit() {
+        let mut resolver = MockIdentityResolver::new();
+        resolver.add_identity("bob.test.com", "did:plc:bob456");
+        resolver.add_identity("charlie.test.com", "did:plc:charlie789");
+
+        // Limit to 2 mentions
+        let limits = FacetLimits {
+            mentions_max: 2,
+            tags_max: 5,
+            links_max: 5,
+            max: 10,
+        };
+
+        let text = "Join @alice.bsky.social @bob.test.com @charlie.test.com";
+        let facets = parse_facets_from_text(text, &resolver, &limits).await;
+
+        assert!(facets.is_some());
+        let facets = facets.unwrap();
+        // Should only have 2 mentions (alice and bob), charlie should be skipped
+        assert_eq!(facets.len(), 2);
+
+        // Verify they're both mentions
+        for facet in &facets {
+            assert!(matches!(facet.features[0], FacetFeature::Mention(_)));
+        }
+    }
+
+    #[tokio::test]
+    async fn test_parse_facets_with_global_limit() {
+        let mut resolver = MockIdentityResolver::new();
+        resolver.add_identity("bob.test.com", "did:plc:bob456");
+
+        // Very restrictive global limit
+        let limits = FacetLimits {
+            mentions_max: 5,
+            tags_max: 5,
+            links_max: 5,
+            max: 3, // Only allow 3 total facets
+        };
+
+        let text =
+            "Join @alice.bsky.social @bob.test.com at https://example.com #rust #golang #python";
+        let facets = parse_facets_from_text(text, &resolver, &limits).await;
+
+        assert!(facets.is_some());
+        let facets = facets.unwrap();
+        // Should be truncated to 3 facets total
+        assert_eq!(facets.len(), 3);
+    }
+
+    #[test]
+    fn test_parse_urls_multiple_links() {
+        let text = "IETF124 is happening in Montreal, Nov 1st to 7th https://www.ietf.org/meeting/124/\n\nWe're confirmed for two days of ATProto community sessions on Monday, Nov 3rd & Tuesday, Mov 4th at ECTO Co-Op. Many of us will also be participating in the free-to-attend IETF hackathon on Sunday, Nov 2nd.\n\nLatest updates and attendees in the forum https://discourse.atprotocol.community/t/update-on-timing-and-plan-for-montreal/164";
+
+        let facets = parse_urls(text);
+
+        // Should find both URLs
+        assert_eq!(
+            facets.len(),
+            2,
+            "Expected 2 URLs but found {}",
+            facets.len()
+        );
+
+        // Check first URL
+        if let Some(FacetFeature::Link(link)) = facets[0].features.first() {
+            assert_eq!(link.uri, "https://www.ietf.org/meeting/124/");
+        } else {
+            panic!("Expected Link feature");
+        }
+
+        // Check second URL
+        if let Some(FacetFeature::Link(link)) = facets[1].features.first() {
+            assert_eq!(
+                link.uri,
+                "https://discourse.atprotocol.community/t/update-on-timing-and-plan-for-montreal/164"
+            );
+        } else {
+            panic!("Expected Link feature");
+        }
+    }
+
+    #[test]
+    fn test_parse_urls_with_html_entity() {
+        // Test with the HTML entity &amp; in the text
+        let text = "IETF124 is happening in Montreal, Nov 1st to 7th https://www.ietf.org/meeting/124/\n\nWe're confirmed for two days of ATProto community sessions on Monday, Nov 3rd &amp; Tuesday, Mov 4th at ECTO Co-Op. Many of us will also be participating in the free-to-attend IETF hackathon on Sunday, Nov 2nd.\n\nLatest updates and attendees in the forum https://discourse.atprotocol.community/t/update-on-timing-and-plan-for-montreal/164";
+
+        let facets = parse_urls(text);
+
+        // Should find both URLs
+        assert_eq!(
+            facets.len(),
+            2,
+            "Expected 2 URLs but found {}",
+            facets.len()
+        );
+
+        // Check first URL
+        if let Some(FacetFeature::Link(link)) = facets[0].features.first() {
+            assert_eq!(link.uri, "https://www.ietf.org/meeting/124/");
+        } else {
+            panic!("Expected Link feature");
+        }
+
+        // Check second URL
+        if let Some(FacetFeature::Link(link)) = facets[1].features.first() {
+            assert_eq!(
+                link.uri,
+                "https://discourse.atprotocol.community/t/update-on-timing-and-plan-for-montreal/164"
+            );
+        } else {
+            panic!("Expected Link feature");
+        }
+    }
+
+    #[test]
+    fn test_byte_offset_with_html_entities() {
+        // This test demonstrates that HTML entity escaping shifts byte positions.
+        // The byte positions shift:
+        // In original: '&' is at byte 8 (1 byte)
+        // In escaped: '&amp;' starts at byte 8 (5 bytes)
+        // This causes facet byte offsets to be misaligned if text is escaped before rendering.
+
+        // If we have a URL after the ampersand in the original:
+        let original_with_url = "Nov 3rd & Tuesday https://example.com";
+        let escaped_with_url = "Nov 3rd &amp; Tuesday https://example.com";
+
+        // Parse URLs from both versions
+        let original_facets = parse_urls(original_with_url);
+        let escaped_facets = parse_urls(escaped_with_url);
+
+        // Both should find the URL, but at different byte positions
+        assert_eq!(original_facets.len(), 1);
+        assert_eq!(escaped_facets.len(), 1);
+
+        // The byte positions will be different
+        assert_eq!(original_facets[0].index.byte_start, 18); // After "Nov 3rd & Tuesday "
+        assert_eq!(escaped_facets[0].index.byte_start, 22); // After "Nov 3rd &amp; Tuesday " (4 extra bytes for &amp;)
+    }
+
+    #[test]
+    fn test_parse_urls_from_atproto_record_text() {
+        // Test parsing URLs from real AT Protocol record description text.
+        // This demonstrates the correct byte positions that should be used for facets.
+        let text = "Dev, Power Users, and Generally inquisitive folks get a completely unprofessionally amateur interview. Just a yap sesh where chat is part of the call!\n\n✨the daniel✨ & I will be on a Zoom call and I will stream out to https://stream.place/psingletary.com\n\nSubscribe to the publications! https://atprotocalls.leaflet.pub/";
+
+        let facets = parse_urls(text);
+
+        assert_eq!(facets.len(), 2, "Should find 2 URLs");
+
+        // First URL: https://stream.place/psingletary.com
+        assert_eq!(facets[0].index.byte_start, 221);
+        assert_eq!(facets[0].index.byte_end, 257);
+        if let Some(FacetFeature::Link(link)) = facets[0].features.first() {
+            assert_eq!(link.uri, "https://stream.place/psingletary.com");
+        }
+
+        // Second URL: https://atprotocalls.leaflet.pub/
+        assert_eq!(facets[1].index.byte_start, 290);
+        assert_eq!(facets[1].index.byte_end, 323);
+        if let Some(FacetFeature::Link(link)) = facets[1].features.first() {
+            assert_eq!(link.uri, "https://atprotocalls.leaflet.pub/");
+        }
+
+        // Verify the byte slices match the expected text
+        let text_bytes = text.as_bytes();
+        assert_eq!(
+            std::str::from_utf8(&text_bytes[221..257]).unwrap(),
+            "https://stream.place/psingletary.com"
+        );
+        assert_eq!(
+            std::str::from_utf8(&text_bytes[290..323]).unwrap(),
+            "https://atprotocalls.leaflet.pub/"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_parse_mentions_basic() {
+        let resolver = MockIdentityResolver::new();
+        let limits = FacetLimits::default();
+        let text = "Hello @alice.bsky.social!";
+        let facets = parse_mentions(text, &resolver, &limits).await;
+
+        assert_eq!(facets.len(), 1);
+        assert_eq!(facets[0].index.byte_start, 6);
+        assert_eq!(facets[0].index.byte_end, 24);
+        if let Some(FacetFeature::Mention(mention)) = facets[0].features.first() {
+            assert_eq!(mention.did, "did:plc:alice123");
+        } else {
+            panic!("Expected Mention feature");
+        }
+    }
+
+    #[tokio::test]
+    async fn test_parse_mentions_multiple() {
+        let mut resolver = MockIdentityResolver::new();
+        resolver.add_identity("bob.example.com", "did:plc:bob456");
+        let limits = FacetLimits::default();
+        let text = "CC @alice.bsky.social and @bob.example.com";
+        let facets = parse_mentions(text, &resolver, &limits).await;
+
+        assert_eq!(facets.len(), 2);
+        if let Some(FacetFeature::Mention(mention)) = facets[0].features.first() {
+            assert_eq!(mention.did, "did:plc:alice123");
+        }
+        if let Some(FacetFeature::Mention(mention)) = facets[1].features.first() {
+            assert_eq!(mention.did, "did:plc:bob456");
+        }
+    }
+
+    #[tokio::test]
+    async fn test_parse_mentions_unresolvable() {
+        let resolver = MockIdentityResolver::new();
+        let limits = FacetLimits::default();
+        // unknown.handle.com is not in the resolver
+        let text = "Hello @unknown.handle.com!";
+        let facets = parse_mentions(text, &resolver, &limits).await;
+
+        // Should be empty since the handle can't be resolved
+        assert_eq!(facets.len(), 0);
+    }
+
+    #[tokio::test]
+    async fn test_parse_mentions_in_url_excluded() {
+        let resolver = MockIdentityResolver::new();
+        let limits = FacetLimits::default();
+        // The @smokesignal.events is inside a URL and should not be parsed as a mention
+        let text = "Check https://tangled.org/@smokesignal.events";
+        let facets = parse_mentions(text, &resolver, &limits).await;
+
+        // Should be empty since the mention is inside a URL
+        assert_eq!(facets.len(), 0);
+    }
+
+    #[test]
+    fn test_parse_tags_basic() {
+        let text = "Learning #rust today!";
+        let facets = parse_tags(text);
+
+        assert_eq!(facets.len(), 1);
+        assert_eq!(facets[0].index.byte_start, 9);
+        assert_eq!(facets[0].index.byte_end, 14);
+        if let Some(FacetFeature::Tag(tag)) = facets[0].features.first() {
+            assert_eq!(tag.tag, "rust");
+        } else {
+            panic!("Expected Tag feature");
+        }
+    }
+
+    #[test]
+    fn test_parse_tags_multiple() {
+        let text = "#rust #golang #python are great!";
+        let facets = parse_tags(text);
+
+        assert_eq!(facets.len(), 3);
+        if let Some(FacetFeature::Tag(tag)) = facets[0].features.first() {
+            assert_eq!(tag.tag, "rust");
+        }
+        if let Some(FacetFeature::Tag(tag)) = facets[1].features.first() {
+            assert_eq!(tag.tag, "golang");
+        }
+        if let Some(FacetFeature::Tag(tag)) = facets[2].features.first() {
+            assert_eq!(tag.tag, "python");
+        }
+    }
+
+    #[test]
+    fn test_parse_tags_excludes_numeric() {
+        let text = "Item #42 is special #test123";
+        let facets = parse_tags(text);
+
+        // #42 should be excluded (purely numeric), #test123 should be included
+        assert_eq!(facets.len(), 1);
+        if let Some(FacetFeature::Tag(tag)) = facets[0].features.first() {
+            assert_eq!(tag.tag, "test123");
+        }
+    }
+
+    #[test]
+    fn test_parse_urls_basic() {
+        let text = "Visit https://example.com today!";
+        let facets = parse_urls(text);
+
+        assert_eq!(facets.len(), 1);
+        assert_eq!(facets[0].index.byte_start, 6);
+        assert_eq!(facets[0].index.byte_end, 25);
+        if let Some(FacetFeature::Link(link)) = facets[0].features.first() {
+            assert_eq!(link.uri, "https://example.com");
+        }
+    }
+
+    #[test]
+    fn test_parse_urls_with_path() {
+        let text = "Check https://example.com/path/to/page?query=1#section";
+        let facets = parse_urls(text);
+
+        assert_eq!(facets.len(), 1);
+        if let Some(FacetFeature::Link(link)) = facets[0].features.first() {
+            assert_eq!(link.uri, "https://example.com/path/to/page?query=1#section");
+        }
+    }
+
+    #[test]
+    fn test_facet_limits_default() {
+        let limits = FacetLimits::default();
+        assert_eq!(limits.mentions_max, 5);
+        assert_eq!(limits.tags_max, 5);
+        assert_eq!(limits.links_max, 5);
+        assert_eq!(limits.max, 10);
+    }
+}

crates/atproto-extras/src/lib.rs

···
+//! Extra utilities for AT Protocol applications.
+//!
+//! This crate provides additional utilities that complement the core AT Protocol
+//! identity and record crates. Currently, it focuses on rich text facet parsing.
+//!
+//! ## Features
+//!
+//! - **Facet Parsing**: Extract mentions, URLs, and hashtags from plain text
+//!   with correct UTF-8 byte offset calculation
+//! - **Identity Integration**: Resolve mention handles to DIDs during parsing
+//!
+//! ## Example
+//!
+//! ```ignore
+//! use atproto_extras::{parse_facets_from_text, FacetLimits};
+//!
+//! // Parse facets from text (requires an IdentityResolver)
+//! let text = "Hello @alice.bsky.social! Check out https://example.com #rust";
+//! let limits = FacetLimits::default();
+//! let facets = parse_facets_from_text(text, &resolver, &limits).await;
+//! ```
+//!
+//! ## Byte Offset Calculation
+//!
+//! This implementation correctly uses UTF-8 byte offsets as required by AT Protocol.
+//! The facets use "inclusive start and exclusive end" byte ranges. All parsing is done
+//! using `regex::bytes::Regex` which operates on byte slices and returns byte positions,
+//! ensuring correct handling of multi-byte UTF-8 characters (emojis, CJK, accented chars).
+
+#![forbid(unsafe_code)]
+#![warn(missing_docs)]
+
+/// Rich text facet parsing for AT Protocol.
+///
+/// This module provides functionality for extracting semantic annotations (facets)
+/// from plain text. Facets include:
+///
+/// - **Mentions**: User handles prefixed with `@` (e.g., `@alice.bsky.social`)
+/// - **Links**: HTTP/HTTPS URLs
+/// - **Tags**: Hashtags prefixed with `#` or `＃` (e.g., `#rust`)
+///
+/// ## Byte Offsets
+///
+/// All facet indices use UTF-8 byte offsets, not character indices. This is
+/// critical for correct handling of multi-byte characters like emojis or
+/// non-ASCII text.
+pub mod facets;
+
+/// Re-export commonly used types for convenience.
+pub use facets::{FacetLimits, parse_facets_from_text, parse_mentions, parse_tags, parse_urls};