more

lib/htmlrw_check/attr_utils.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Common attribute utilities used across checkers.
+
+    This module provides simple helper functions for working with raw
+    attribute lists (name-value pairs). These utilities are used by
+    checkers that need to inspect attributes without full typed parsing.
+
+    For typed attribute access, see the {!Attr} module.
+*)
+
+(** {1 Types} *)
+
+type attrs = (string * string) list
+(** Raw attribute list as name-value pairs. *)
+
+(** {1 Attribute Lookup} *)
+
+val has_attr : string -> attrs -> bool
+(** [has_attr name attrs] checks if an attribute exists.
+
+    The comparison is case-insensitive.
+
+    @param name The attribute name to look for (lowercase)
+    @param attrs The attribute list
+    @return [true] if the attribute is present *)
+
+val get_attr : string -> attrs -> string option
+(** [get_attr name attrs] gets an attribute value.
+
+    The comparison is case-insensitive.
+
+    @param name The attribute name to look for (lowercase)
+    @param attrs The attribute list
+    @return [Some value] if found, [None] otherwise *)
+
+val get_attr_or : string -> default:string -> attrs -> string
+(** [get_attr_or name ~default attrs] gets an attribute value with a default.
+
+    @param name The attribute name to look for (lowercase)
+    @param default The default value if not found
+    @param attrs The attribute list
+    @return The attribute value or the default *)
+
+val is_non_empty_attr : string -> attrs -> bool
+(** [is_non_empty_attr name attrs] checks if an attribute exists with non-empty value.
+
+    The value is considered non-empty if it contains non-whitespace characters.
+
+    @param name The attribute name to look for (lowercase)
+    @param attrs The attribute list
+    @return [true] if the attribute exists and has a non-empty value *)

lib/htmlrw_check/element/attr.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Typed HTML5 attribute representations using polymorphic variants.
+
+    This module provides typed representations for HTML attributes with
+    proper value types for enumerated attributes. Parsing raw attribute
+    name-value pairs produces typed variants that can be pattern-matched
+    with exhaustiveness checking.
+
+    {2 Design Philosophy}
+
+    HTML5 attributes have specific value constraints that this module
+    encodes in the type system:
+
+    - Boolean attributes: Present means true (e.g., [disabled], [checked])
+    - Enumerated attributes: Fixed set of valid values (e.g., [dir], [method])
+    - Numeric attributes: Integer or float values (e.g., [tabindex], [colspan])
+    - URL attributes: String values representing URLs (e.g., [href], [src])
+    - Free-form attributes: Any string value (e.g., [class], [title])
+
+    {2 Parsing Strategy}
+
+    Attributes are parsed with validation:
+    - Known attributes are parsed into typed variants
+    - Invalid values for enumerated attributes fall back to [Unknown_attr]
+    - Unknown attribute names are captured as [Unknown_attr]
+    - Special handling for [data-*] and [aria-*] prefixed attributes
+
+    @see <https://html.spec.whatwg.org/multipage/dom.html#global-attributes>
+         HTML Standard: Global attributes
+*)
+
+(** {1 Attribute Value Types}
+
+    These types represent the valid values for enumerated HTML attributes. *)
+
+(** Direction attribute values for [dir]. *)
+type dir_value = [ `Ltr | `Rtl | `Auto ]
+
+(** Hidden attribute values. *)
+type hidden_value = [ `Hidden | `Until_found ]
+
+(** Popover attribute values. *)
+type popover_value = [ `Auto | `Manual | `Hint ]
+
+(** Link target attribute values. *)
+type target_value = [ `Self | `Blank | `Parent | `Top | `Named of string ]
+
+(** Image/resource loading behavior. *)
+type loading_value = [ `Eager | `Lazy ]
+
+(** Image decoding hint. *)
+type decoding_value = [ `Sync | `Async | `Auto ]
+
+(** Fetch priority hint. *)
+type fetchpriority_value = [ `High | `Low | `Auto ]
+
+(** CORS settings. *)
+type crossorigin_value = [ `Anonymous | `Use_credentials ]
+
+(** Media preload hint. *)
+type preload_value = [ `None | `Metadata | `Auto ]
+
+(** Form method values. *)
+type method_value = [ `Get | `Post | `Dialog ]
+
+(** Form encoding type values. *)
+type enctype_value = [ `Urlencoded | `Multipart | `Plain ]
+
+(** Textarea wrap mode. *)
+type wrap_value = [ `Soft | `Hard ]
+
+(** Table cell scope. *)
+type scope_value = [ `Row | `Col | `Rowgroup | `Colgroup ]
+
+(** Input element type values. *)
+type input_type = [
+  | `Hidden | `Text | `Search | `Tel | `Url | `Email | `Password
+  | `Date | `Month | `Week | `Time | `Datetime_local | `Number
+  | `Range | `Color | `Checkbox | `Radio | `File | `Submit
+  | `Image | `Reset | `Button
+]
+
+(** Button element type values. *)
+type button_type = [ `Submit | `Reset | `Button ]
+
+(** Referrer policy values. *)
+type referrerpolicy_value = [
+  | `No_referrer | `No_referrer_when_downgrade | `Origin
+  | `Origin_when_cross_origin | `Same_origin | `Strict_origin
+  | `Strict_origin_when_cross_origin | `Unsafe_url
+]
+
+(** Iframe sandbox flags. *)
+type sandbox_flag = [
+  | `Allow_downloads | `Allow_forms | `Allow_modals | `Allow_orientation_lock
+  | `Allow_pointer_lock | `Allow_popups | `Allow_popups_to_escape_sandbox
+  | `Allow_presentation | `Allow_same_origin | `Allow_scripts
+  | `Allow_top_navigation | `Allow_top_navigation_by_user_activation
+  | `Allow_top_navigation_to_custom_protocols
+]
+
+(** Enter key hint values for virtual keyboards. *)
+type enterkeyhint_value = [
+  | `Enter | `Done | `Go | `Next | `Previous | `Search | `Send
+]
+
+(** Input mode hint for virtual keyboards. *)
+type inputmode_value = [
+  | `None | `Text | `Decimal | `Numeric | `Tel | `Search | `Email | `Url
+]
+
+(** Content editable values. *)
+type contenteditable_value = [ `True | `False | `Plaintext_only ]
+
+(** Autocapitalize values. *)
+type autocapitalize_value = [
+  | `Off | `None | `On | `Sentences | `Words | `Characters
+]
+
+(** Image map shape values. *)
+type shape_value = [ `Rect | `Circle | `Poly | `Default ]
+
+(** Input capture values for file inputs. *)
+type capture_value = [ `User | `Environment ]
+
+(** Ordered list type values. *)
+type list_type_value = [
+  | `Decimal | `Lower_alpha | `Upper_alpha | `Lower_roman | `Upper_roman
+]
+
+(** Track element kind values. *)
+type kind_value = [
+  | `Subtitles | `Captions | `Descriptions | `Chapters | `Metadata
+]
+
+(** {1 Typed Attribute Variant} *)
+
+(** Typed attribute representation.
+
+    This type covers all HTML5 attributes with appropriate value types.
+    Attributes are organized into logical groups. *)
+type t = [
+  (* Global attributes *)
+  | `Id of string
+  | `Class of string
+  | `Style of string
+  | `Title of string
+  | `Lang of string
+  | `Dir of dir_value
+  | `Hidden of hidden_value option
+  | `Tabindex of int
+  | `Accesskey of string
+  | `Autocapitalize of autocapitalize_value
+  | `Autofocus
+  | `Contenteditable of contenteditable_value option
+  | `Draggable of bool
+  | `Enterkeyhint of enterkeyhint_value
+  | `Inert
+  | `Inputmode of inputmode_value
+  | `Is of string
+  | `Nonce of string
+  | `Popover of popover_value option
+  | `Slot of string
+  | `Spellcheck of bool option
+  | `Translate of bool
+  | `Exportparts of string
+  | `Part of string
+
+  (* Microdata *)
+  | `Itemscope
+  | `Itemtype of string
+  | `Itemprop of string
+  | `Itemid of string
+  | `Itemref of string
+
+  (* ARIA *)
+  | `Role of string
+  | `Aria of string * string
+
+  (* Event handlers *)
+  | `Event of string * string
+
+  (* Link/navigation attributes *)
+  | `Href of string
+  | `Target of target_value
+  | `Rel of string
+  | `Download of string option
+  | `Hreflang of string
+  | `Ping of string
+  | `Referrerpolicy of referrerpolicy_value
+  | `Type_link of string
+
+  (* Media/resource attributes *)
+  | `Src of string
+  | `Srcset of string
+  | `Sizes of string
+  | `Alt of string
+  | `Width of string
+  | `Height of string
+  | `Loading of loading_value
+  | `Decoding of decoding_value
+  | `Fetchpriority of fetchpriority_value
+  | `Crossorigin of crossorigin_value option
+  | `Ismap
+  | `Usemap of string
+  | `Media of string
+
+  (* Audio/Video specific *)
+  | `Controls
+  | `Autoplay
+  | `Loop
+  | `Muted
+  | `Preload of preload_value
+  | `Poster of string
+  | `Playsinline
+
+  (* Image map *)
+  | `Coords of string
+  | `Shape of shape_value
+
+  (* iframe *)
+  | `Sandbox of sandbox_flag list option
+  | `Allow of string
+  | `Allowfullscreen
+  | `Srcdoc of string
+  | `Csp of string
+
+  (* Form attributes *)
+  | `Action of string
+  | `Method of method_value
+  | `Enctype of enctype_value
+  | `Novalidate
+  | `Accept_charset of string
+  | `Autocomplete of string
+  | `Name of string
+  | `Form of string
+
+  (* Form control attributes *)
+  | `Value of string
+  | `Type_input of input_type
+  | `Type_button of button_type
+  | `Disabled
+  | `Readonly
+  | `Required
+  | `Checked
+  | `Selected
+  | `Multiple
+  | `Placeholder of string
+  | `Min of string
+  | `Max of string
+  | `Step of string
+  | `Minlength of int
+  | `Maxlength of int
+  | `Pattern of string
+  | `Size of int
+  | `Cols of int
+  | `Rows of int
+  | `Wrap of wrap_value
+  | `Accept of string
+  | `Capture of capture_value
+  | `Dirname of string
+  | `For of string
+  | `List of string
+
+  (* Form submission attributes *)
+  | `Formaction of string
+  | `Formmethod of method_value
+  | `Formenctype of enctype_value
+  | `Formnovalidate
+  | `Formtarget of target_value
+
+  (* Table attributes *)
+  | `Colspan of int
+  | `Rowspan of int
+  | `Headers of string
+  | `Scope of scope_value
+  | `Span of int
+
+  (* Details/Dialog *)
+  | `Open
+
+  (* Script *)
+  | `Async
+  | `Defer
+  | `Integrity of string
+  | `Nomodule
+  | `Blocking of string
+  | `Type_script of string
+
+  (* Meta *)
+  | `Charset of string
+  | `Content of string
+  | `Http_equiv of string
+
+  (* Link element *)
+  | `As of string
+  | `Imagesizes of string
+  | `Imagesrcset of string
+
+  (* Object/Embed *)
+  | `Data_object of string
+
+  (* Output *)
+  | `For_output of string
+
+  (* Meter/Progress *)
+  | `Low of float
+  | `High of float
+  | `Optimum of float
+
+  (* Time *)
+  | `Datetime of string
+
+  (* Ol *)
+  | `Start of int
+  | `Reversed
+  | `Type_list of list_type_value
+
+  (* Track *)
+  | `Kind of kind_value
+  | `Srclang of string
+  | `Default
+
+  (* Td/Th *)
+  | `Abbr of string
+
+  (* Data attributes *)
+  | `Data_attr of string * string
+
+  (* RDFa *)
+  | `Property of string
+  | `Typeof of string
+  | `Resource of string
+  | `Prefix of string
+  | `Vocab of string
+  | `About of string
+  | `Datatype of string
+  | `Inlist
+  | `Rev of string
+
+  (* Escape hatch *)
+  | `Unknown_attr of string * string
+]
+
+(** {1 Parsing Functions} *)
+
+val parse_dir : string -> dir_value option
+(** [parse_dir value] parses a direction attribute value. *)
+
+val parse_target : string -> target_value
+(** [parse_target value] parses a target attribute value. *)
+
+val parse_loading : string -> loading_value option
+(** [parse_loading value] parses a loading attribute value. *)
+
+val parse_decoding : string -> decoding_value option
+(** [parse_decoding value] parses a decoding attribute value. *)
+
+val parse_fetchpriority : string -> fetchpriority_value option
+(** [parse_fetchpriority value] parses a fetchpriority attribute value. *)
+
+val parse_crossorigin : string -> crossorigin_value option
+(** [parse_crossorigin value] parses a crossorigin attribute value. *)
+
+val parse_preload : string -> preload_value option
+(** [parse_preload value] parses a preload attribute value. *)
+
+val parse_method : string -> method_value option
+(** [parse_method value] parses a form method attribute value. *)
+
+val parse_enctype : string -> enctype_value option
+(** [parse_enctype value] parses a form enctype attribute value. *)
+
+val parse_wrap : string -> wrap_value option
+(** [parse_wrap value] parses a textarea wrap attribute value. *)
+
+val parse_scope : string -> scope_value option
+(** [parse_scope value] parses a table scope attribute value. *)
+
+val parse_input_type : string -> input_type option
+(** [parse_input_type value] parses an input type attribute value. *)
+
+val parse_button_type : string -> button_type option
+(** [parse_button_type value] parses a button type attribute value. *)
+
+val parse_shape : string -> shape_value option
+(** [parse_shape value] parses an area shape attribute value. *)
+
+val parse_capture : string -> capture_value option
+(** [parse_capture value] parses an input capture attribute value. *)
+
+val parse_list_type : string -> list_type_value option
+(** [parse_list_type value] parses an ordered list type attribute value. *)
+
+val parse_kind : string -> kind_value option
+(** [parse_kind value] parses a track kind attribute value. *)
+
+val parse_referrerpolicy : string -> referrerpolicy_value option
+(** [parse_referrerpolicy value] parses a referrer policy attribute value. *)
+
+val parse_sandbox_flag : string -> sandbox_flag option
+(** [parse_sandbox_flag value] parses a single sandbox flag token. *)
+
+val parse_sandbox : string -> sandbox_flag list option
+(** [parse_sandbox value] parses a space-separated sandbox attribute value. *)
+
+val parse_enterkeyhint : string -> enterkeyhint_value option
+(** [parse_enterkeyhint value] parses an enterkeyhint attribute value. *)
+
+val parse_inputmode : string -> inputmode_value option
+(** [parse_inputmode value] parses an inputmode attribute value. *)
+
+val parse_contenteditable : string -> contenteditable_value option
+(** [parse_contenteditable value] parses a contenteditable attribute value. *)
+
+val parse_autocapitalize : string -> autocapitalize_value option
+(** [parse_autocapitalize value] parses an autocapitalize attribute value. *)
+
+val parse_hidden : string -> hidden_value option
+(** [parse_hidden value] parses a hidden attribute value. *)
+
+val parse_popover : string -> popover_value option
+(** [parse_popover value] parses a popover attribute value. *)
+
+val parse_int : string -> int option
+(** [parse_int value] attempts to parse an integer from a string. *)
+
+val parse_float : string -> float option
+(** [parse_float value] attempts to parse a float from a string. *)
+
+val parse_bool : string -> bool option
+(** [parse_bool value] parses a boolean attribute value. *)
+
+val parse_attr : string -> string -> t
+(** [parse_attr name value] parses a single attribute name-value pair.
+
+    @param name The attribute name
+    @param value The attribute value
+    @return A typed attribute variant
+
+    {b Example:}
+    {[
+      parse_attr "class" "container"  (* `Class "container" *)
+      parse_attr "disabled" ""        (* `Disabled *)
+      parse_attr "data-id" "123"      (* `Data_attr ("id", "123") *)
+    ]} *)
+
+val parse_attrs : (string * string) list -> t list
+(** [parse_attrs attrs] parses multiple attributes.
+
+    @param attrs List of (name, value) pairs
+    @return List of typed attributes *)
+
+(** {1 Accessor Functions} *)
+
+val get_id : t list -> string option
+(** [get_id attrs] extracts the id attribute value if present. *)
+
+val get_class : t list -> string option
+(** [get_class attrs] extracts the class attribute value if present. *)
+
+val get_href : t list -> string option
+(** [get_href attrs] extracts the href attribute value if present. *)
+
+val get_src : t list -> string option
+(** [get_src attrs] extracts the src attribute value if present. *)
+
+val get_alt : t list -> string option
+(** [get_alt attrs] extracts the alt attribute value if present. *)
+
+val get_name : t list -> string option
+(** [get_name attrs] extracts the name attribute value if present. *)
+
+val get_value : t list -> string option
+(** [get_value attrs] extracts the value attribute value if present. *)
+
+val get_role : t list -> string option
+(** [get_role attrs] extracts the role attribute value if present. *)
+
+val get_aria : string -> t list -> string option
+(** [get_aria name attrs] extracts a specific aria-* attribute value.
+
+    @param name The aria attribute name without the "aria-" prefix *)
+
+val get_data : string -> t list -> string option
+(** [get_data name attrs] extracts a specific data-* attribute value.
+
+    @param name The data attribute name without the "data-" prefix *)
+
+val has_disabled : t list -> bool
+(** [has_disabled attrs] checks if the disabled attribute is present. *)
+
+val has_required : t list -> bool
+(** [has_required attrs] checks if the required attribute is present. *)
+
+val has_readonly : t list -> bool
+(** [has_readonly attrs] checks if the readonly attribute is present. *)
+
+val has_checked : t list -> bool
+(** [has_checked attrs] checks if the checked attribute is present. *)
+
+val has_autofocus : t list -> bool
+(** [has_autofocus attrs] checks if the autofocus attribute is present. *)
+
+val has_hidden : t list -> bool
+(** [has_hidden attrs] checks if the hidden attribute is present. *)
+
+val has_inert : t list -> bool
+(** [has_inert attrs] checks if the inert attribute is present. *)
+
+val has_open : t list -> bool
+(** [has_open attrs] checks if the open attribute is present. *)
+
+val get_all_aria : t list -> (string * string) list
+(** [get_all_aria attrs] extracts all aria-* attributes. *)
+
+val get_all_data : t list -> (string * string) list
+(** [get_all_data attrs] extracts all data-* attributes. *)
+
+val find : (t -> 'a option) -> t list -> 'a option
+(** [find f attrs] finds the first attribute matching predicate [f]. *)
+
+val exists : (t -> bool) -> t list -> bool
+(** [exists f attrs] checks if any attribute matches predicate [f]. *)
+
+val filter : (t -> bool) -> t list -> t list
+(** [filter f attrs] filters attributes matching predicate [f]. *)

lib/htmlrw_check/element/element.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Typed HTML5 element representation.
+
+    This module combines tags and attributes into a complete typed element
+    representation. Elements are created from raw input (tag name, namespace,
+    attributes) and provide typed accessors for validation and manipulation.
+
+    {2 Design Philosophy}
+
+    An element in this module represents a complete typed view of an HTML
+    element, including:
+
+    - The element's tag (typed via {!Tag.element_tag})
+    - Typed attributes (via {!Attr.t} list)
+    - Raw attributes (for fallback access)
+
+    This dual representation allows checkers to use typed pattern matching
+    for common cases while falling back to raw strings when needed.
+
+    {2 Usage Example}
+
+    {[
+      let elem = Element.create
+        ~name:"input"
+        ~namespace:None
+        ~attrs:[("type", "email"); ("required", ""); ("class", "form-input")]
+      in
+      match elem.tag with
+      | Tag.Html `Input ->
+        if Element.has_required elem then
+          (* Validate required input *)
+          ()
+      | _ -> ()
+    ]}
+
+    @see 'Tag' for element tag types
+    @see 'Attr' for attribute types
+*)
+
+(** {1 Element Type} *)
+
+(** A typed HTML element.
+
+    @field tag The element's tag classification
+    @field attrs Typed attributes parsed from raw input
+    @field raw_attrs Original attribute name-value pairs for fallback *)
+type t = {
+  tag : Tag.element_tag;
+  attrs : Attr.t list;
+  raw_attrs : (string * string) list;
+}
+
+(** {1 Construction} *)
+
+val create : name:string -> namespace:string option -> attrs:(string * string) list -> t
+(** [create ~name ~namespace ~attrs] creates a typed element.
+
+    @param name The element's tag name
+    @param namespace Optional namespace URI (for SVG/MathML)
+    @param attrs Raw attribute name-value pairs
+    @return A typed element
+
+    {b Example:}
+    {[
+      let div = Element.create ~name:"div" ~namespace:None
+        ~attrs:[("class", "container"); ("id", "main")]
+    ]} *)
+
+(** {1 Tag Accessors} *)
+
+val tag : t -> Tag.element_tag
+(** [tag elem] returns the element's tag. *)
+
+val tag_name : t -> string
+(** [tag_name elem] returns the element's tag name as a string. *)
+
+val is_html_tag : Tag.html_tag -> t -> bool
+(** [is_html_tag expected elem] checks if the element is a specific HTML tag.
+
+    @param expected The expected HTML tag variant
+    @param elem The element to check
+    @return [true] if the element matches *)
+
+val as_html_tag : t -> Tag.html_tag option
+(** [as_html_tag elem] extracts the HTML tag if this is an HTML element.
+
+    @return [Some tag] for HTML elements, [None] for SVG/MathML/Custom/Unknown *)
+
+(** {1 Attribute Accessors} *)
+
+val attrs : t -> Attr.t list
+(** [attrs elem] returns the typed attributes. *)
+
+val raw_attrs : t -> (string * string) list
+(** [raw_attrs elem] returns the original raw attributes. *)
+
+val get_id : t -> string option
+(** [get_id elem] extracts the id attribute value. *)
+
+val get_class : t -> string option
+(** [get_class elem] extracts the class attribute value. *)
+
+val get_href : t -> string option
+(** [get_href elem] extracts the href attribute value. *)
+
+val get_src : t -> string option
+(** [get_src elem] extracts the src attribute value. *)
+
+val get_alt : t -> string option
+(** [get_alt elem] extracts the alt attribute value. *)
+
+val get_name : t -> string option
+(** [get_name elem] extracts the name attribute value. *)
+
+val get_value : t -> string option
+(** [get_value elem] extracts the value attribute value. *)
+
+val get_role : t -> string option
+(** [get_role elem] extracts the role attribute value. *)
+
+val get_aria : string -> t -> string option
+(** [get_aria name elem] extracts a specific aria-* attribute value.
+
+    @param name The aria attribute name without the "aria-" prefix *)
+
+val get_data : string -> t -> string option
+(** [get_data name elem] extracts a specific data-* attribute value.
+
+    @param name The data attribute name without the "data-" prefix *)
+
+val has_disabled : t -> bool
+(** [has_disabled elem] checks if the disabled attribute is present. *)
+
+val has_required : t -> bool
+(** [has_required elem] checks if the required attribute is present. *)
+
+val has_readonly : t -> bool
+(** [has_readonly elem] checks if the readonly attribute is present. *)
+
+val has_checked : t -> bool
+(** [has_checked elem] checks if the checked attribute is present. *)
+
+val has_autofocus : t -> bool
+(** [has_autofocus elem] checks if the autofocus attribute is present. *)
+
+val has_hidden : t -> bool
+(** [has_hidden elem] checks if the hidden attribute is present. *)
+
+val has_inert : t -> bool
+(** [has_inert elem] checks if the inert attribute is present. *)
+
+val has_open : t -> bool
+(** [has_open elem] checks if the open attribute is present. *)
+
+val get_all_aria : t -> (string * string) list
+(** [get_all_aria elem] extracts all aria-* attributes. *)
+
+val get_all_data : t -> (string * string) list
+(** [get_all_data elem] extracts all data-* attributes. *)
+
+(** {1 Raw Attribute Fallback} *)
+
+val get_raw_attr : string -> t -> string option
+(** [get_raw_attr name elem] gets a raw attribute value by name.
+
+    This is useful when the typed representation doesn't capture a specific
+    attribute or when you need the exact original value.
+
+    @param name The attribute name (case-insensitive)
+    @param elem The element
+    @return [Some value] if the attribute exists *)
+
+val has_raw_attr : string -> t -> bool
+(** [has_raw_attr name elem] checks if a raw attribute exists.
+
+    @param name The attribute name (case-insensitive)
+    @param elem The element
+    @return [true] if the attribute is present *)
+
+(** {1 Category Checks}
+
+    These predicates check element categories based on the HTML5 content model. *)
+
+val is_void : t -> bool
+(** [is_void elem] checks if this is a void element (cannot have children).
+
+    @return [true] for br, hr, img, input, etc. *)
+
+val is_heading : t -> bool
+(** [is_heading elem] checks if this is a heading element.
+
+    @return [true] for h1-h6 *)
+
+val heading_level : t -> int option
+(** [heading_level elem] gets the heading level (1-6) if applicable.
+
+    @return [Some level] for h1-h6, [None] otherwise *)
+
+val is_sectioning : t -> bool
+(** [is_sectioning elem] checks if this is sectioning content.
+
+    @return [true] for article, aside, nav, section *)
+
+val is_sectioning_root : t -> bool
+(** [is_sectioning_root elem] checks if this is a sectioning root.
+
+    @return [true] for blockquote, body, details, dialog, fieldset, figure, td *)
+
+val is_embedded : t -> bool
+(** [is_embedded elem] checks if this is embedded content.
+
+    @return [true] for audio, canvas, embed, iframe, img, object, picture, video *)
+
+val is_interactive : t -> bool
+(** [is_interactive elem] checks if this is interactive content.
+
+    @return [true] for focusable/activatable elements *)
+
+val is_form_associated : t -> bool
+(** [is_form_associated elem] checks if this is form-associated.
+
+    @return [true] for elements that can belong to a form *)
+
+val is_labelable : t -> bool
+(** [is_labelable elem] checks if this can be associated with a label.
+
+    @return [true] for button, input, meter, output, progress, select, textarea *)
+
+val is_submittable : t -> bool
+(** [is_submittable elem] checks if this is a submittable form element.
+
+    @return [true] for button, input, select, textarea *)
+
+val is_table_element : t -> bool
+(** [is_table_element elem] checks if this is a table-related element.
+
+    @return [true] for table, tr, td, th, etc. *)
+
+val is_media : t -> bool
+(** [is_media elem] checks if this is a media element.
+
+    @return [true] for audio, video *)
+
+val is_list_container : t -> bool
+(** [is_list_container elem] checks if this is a list container.
+
+    @return [true] for ul, ol, menu, dl *)
+
+val is_transparent : t -> bool
+(** [is_transparent elem] checks if this has a transparent content model.
+
+    @return [true] for a, abbr, audio, canvas, del, ins, map, noscript, etc. *)
+
+val is_phrasing : t -> bool
+(** [is_phrasing elem] checks if this is phrasing content.
+
+    @return [true] for inline-level elements *)
+
+val is_flow : t -> bool
+(** [is_flow elem] checks if this is flow content.
+
+    @return [true] for most body-level elements *)
+
+val is_obsolete : t -> bool
+(** [is_obsolete elem] checks if this is a deprecated element.
+
+    @return [true] for applet, font, marquee, etc. *)
+
+val is_svg : t -> bool
+(** [is_svg elem] checks if this is an SVG element.
+
+    @return [true] if the element is in the SVG namespace *)
+
+val is_mathml : t -> bool
+(** [is_mathml elem] checks if this is a MathML element.
+
+    @return [true] if the element is in the MathML namespace *)
+
+val is_custom : t -> bool
+(** [is_custom elem] checks if this is a custom element.
+
+    @return [true] if the element name contains a hyphen *)
+
+val is_unknown : t -> bool
+(** [is_unknown elem] checks if this is an unknown element.
+
+    @return [true] if the element is not recognized *)
+
+(** {1 Input Type Utilities} *)
+
+val get_input_type : t -> Attr.input_type option
+(** [get_input_type elem] gets the input type for input elements.
+
+    @return [Some type] for input elements with a type, [None] otherwise *)
+
+val get_button_type : t -> Attr.button_type option
+(** [get_button_type elem] gets the button type for button elements.
+
+    @return [Some type] for button elements with a type, [None] otherwise *)
+
+val is_input_type : Attr.input_type -> t -> bool
+(** [is_input_type expected elem] checks if an input has a specific type.
+
+    @param expected The expected input type
+    @param elem The element to check
+    @return [true] if this is an input with the specified type *)
+
+(** {1 Pattern Matching Helpers} *)
+
+val match_html : t -> (Tag.html_tag -> 'a) -> 'a option
+(** [match_html elem f] applies [f] to the HTML tag if present.
+
+    @param elem The element
+    @param f Function to apply to the HTML tag
+    @return [Some (f tag)] for HTML elements, [None] otherwise *)
+
+val when_html_tag : Tag.html_tag -> t -> (unit -> 'a) -> 'a option
+(** [when_html_tag expected elem f] applies [f] if the element matches.
+
+    @param expected The expected HTML tag
+    @param elem The element to check
+    @param f Function to call if the element matches
+    @return [Some (f ())] if matched, [None] otherwise *)
+
+(** {1 Internal} *)
+
+val parse_type_attr : Tag.html_tag -> string -> Attr.t
+(** [parse_type_attr tag value] parses a type attribute for an element.
+
+    Different elements have different valid type values. This function
+    handles context-dependent parsing.
+
+    @param tag The element's HTML tag
+    @param value The type attribute value
+    @return The parsed attribute variant *)
+
+val parse_attrs_for_tag : Tag.element_tag -> (string * string) list -> Attr.t list
+(** [parse_attrs_for_tag tag raw_attrs] parses attributes with element context.
+
+    The type attribute is parsed differently depending on the element tag.
+
+    @param tag The element's tag
+    @param raw_attrs Raw attribute name-value pairs
+    @return List of typed attributes *)

lib/htmlrw_check/element/tag.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Typed HTML5 tag representations using polymorphic variants.
+
+    This module provides compile-time type safety for HTML elements while
+    maintaining escape hatches for unknown/custom elements. Tags are
+    represented using polymorphic variants, enabling pattern matching with
+    exhaustiveness checking while avoiding the overhead of explicit
+    constructors.
+
+    {2 Design Philosophy}
+
+    HTML5 defines over 100 standard elements with specific categories and
+    content models. This module:
+
+    - Provides typed representations for all standard elements
+    - Supports SVG and MathML namespaced elements
+    - Recognizes custom elements (containing hyphens)
+    - Falls back to [Unknown] for unrecognized elements
+
+    {2 Element Categories}
+
+    HTML5 categorizes elements into content categories that define where
+    elements can appear and what they can contain. This module provides
+    predicates for common categories:
+
+    - {!is_void} - Elements that cannot have children
+    - {!is_heading} - Heading elements (h1-h6)
+    - {!is_sectioning} - Elements that create document sections
+    - {!is_phrasing} - Inline/phrasing content elements
+    - {!is_flow} - Block/flow content elements
+
+    @see <https://html.spec.whatwg.org/multipage/dom.html#content-models>
+         HTML Standard: Content models
+*)
+
+(** {1 HTML Tag Types} *)
+
+(** All standard HTML5 elements plus deprecated elements needed by the validator.
+
+    This type covers:
+    - Document metadata elements (html, head, title, etc.)
+    - Sectioning elements (article, section, nav, etc.)
+    - Heading elements (h1-h6)
+    - Grouping content (div, p, ul, ol, etc.)
+    - Text-level semantics (a, em, strong, span, etc.)
+    - Embedded content (img, video, audio, etc.)
+    - Table elements (table, tr, td, th, etc.)
+    - Form elements (form, input, button, etc.)
+    - Interactive elements (details, dialog, summary)
+    - Scripting elements (script, noscript, template)
+    - Deprecated/obsolete elements (font, center, marquee, etc.) *)
+type html_tag = [
+  (* Document metadata *)
+  | `Html | `Head | `Title | `Base | `Link | `Meta | `Style
+
+  (* Sectioning root *)
+  | `Body
+
+  (* Content sectioning *)
+  | `Address | `Article | `Aside | `Footer | `Header | `Hgroup
+  | `Main | `Nav | `Search | `Section
+
+  (* Heading content *)
+  | `H1 | `H2 | `H3 | `H4 | `H5 | `H6
+
+  (* Grouping content *)
+  | `Blockquote | `Dd | `Div | `Dl | `Dt | `Figcaption | `Figure
+  | `Hr | `Li | `Menu | `Ol | `P | `Pre | `Ul
+
+  (* Text-level semantics *)
+  | `A | `Abbr | `B | `Bdi | `Bdo | `Br | `Cite | `Code | `Data
+  | `Dfn | `Em | `I | `Kbd | `Mark | `Q | `Rp | `Rt | `Ruby
+  | `S | `Samp | `Small | `Span | `Strong | `Sub | `Sup | `Time
+  | `U | `Var | `Wbr
+
+  (* Edits *)
+  | `Del | `Ins
+
+  (* Embedded content *)
+  | `Area | `Audio | `Canvas | `Embed | `Iframe | `Img | `Map | `Object
+  | `Picture | `Source | `Track | `Video
+
+  (* Tabular data *)
+  | `Caption | `Col | `Colgroup | `Table | `Tbody | `Td | `Tfoot
+  | `Th | `Thead | `Tr
+
+  (* Forms *)
+  | `Button | `Datalist | `Fieldset | `Form | `Input | `Label
+  | `Legend | `Meter | `Optgroup | `Option | `Output | `Progress
+  | `Select | `Textarea
+
+  (* Interactive elements *)
+  | `Details | `Dialog | `Summary
+
+  (* Scripting *)
+  | `Noscript | `Script | `Slot | `Template
+
+  (* Web Components / Misc *)
+  | `Portal | `Param
+
+  (* Deprecated/obsolete elements *)
+  | `Applet | `Acronym | `Bgsound | `Dir | `Frame | `Frameset
+  | `Noframes | `Isindex | `Keygen | `Listing | `Menuitem | `Nextid
+  | `Noembed | `Plaintext | `Rb | `Rtc | `Strike | `Xmp
+  | `Basefont | `Big | `Blink | `Center | `Font | `Marquee
+  | `Multicol | `Nobr | `Spacer | `Tt | `Image
+]
+
+(** {1 Category Types}
+
+    Type aliases for element subsets, enabling functions that only accept
+    specific categories with compile-time checking. *)
+
+(** Void elements - cannot have children (e.g., br, hr, img, input). *)
+type void_tag = [
+  | `Area | `Base | `Br | `Col | `Embed | `Hr | `Img | `Input
+  | `Link | `Meta | `Source | `Track | `Wbr
+  | `Basefont | `Frame | `Isindex | `Keygen | `Param
+]
+
+(** Heading elements (h1-h6). *)
+type heading_tag = [ `H1 | `H2 | `H3 | `H4 | `H5 | `H6 ]
+
+(** Sectioning content elements that establish document sections. *)
+type sectioning_tag = [ `Article | `Aside | `Nav | `Section ]
+
+(** Sectioning roots that establish their own outline context. *)
+type sectioning_root_tag = [
+  | `Blockquote | `Body | `Details | `Dialog | `Fieldset | `Figure | `Td
+]
+
+(** Embedded content elements. *)
+type embedded_tag = [
+  | `Audio | `Canvas | `Embed | `Iframe | `Img | `Object | `Picture | `Video
+]
+
+(** Interactive content elements (focusable/activatable). *)
+type interactive_tag = [
+  | `A | `Audio | `Button | `Details | `Embed | `Iframe | `Img
+  | `Input | `Label | `Select | `Textarea | `Video
+]
+
+(** Form-associated elements that can belong to a form. *)
+type form_associated_tag = [
+  | `Button | `Fieldset | `Input | `Label | `Object | `Output
+  | `Select | `Textarea | `Meter | `Progress
+]
+
+(** Labelable elements that can be associated with a label. *)
+type labelable_tag = [
+  | `Button | `Input | `Meter | `Output | `Progress | `Select | `Textarea
+]
+
+(** Submittable form elements. *)
+type submittable_tag = [
+  | `Button | `Input | `Select | `Textarea
+]
+
+(** Resettable form elements. *)
+type resettable_tag = [
+  | `Input | `Output | `Select | `Textarea
+]
+
+(** Table-related elements. *)
+type table_tag = [
+  | `Caption | `Col | `Colgroup | `Table | `Tbody | `Td | `Tfoot
+  | `Th | `Thead | `Tr
+]
+
+(** Media elements (audio and video). *)
+type media_tag = [ `Audio | `Video ]
+
+(** List container elements. *)
+type list_container_tag = [ `Ul | `Ol | `Menu | `Dl ]
+
+(** List item elements. *)
+type list_item_tag = [ `Li | `Dd | `Dt ]
+
+(** Script-supporting elements. *)
+type script_supporting_tag = [ `Script | `Template ]
+
+(** Metadata content elements. *)
+type metadata_tag = [ `Base | `Link | `Meta | `Noscript | `Script | `Style | `Template | `Title ]
+
+(** {1 Top-Level Element Type} *)
+
+(** Top-level element classification.
+
+    Elements are classified by namespace and recognition status:
+    - [Html tag] - A known HTML5 element
+    - [Svg name] - An SVG element (preserves original case)
+    - [MathML name] - A MathML element (preserves original case)
+    - [Custom name] - A custom element (contains hyphen)
+    - [Unknown name] - An unrecognized element *)
+type element_tag =
+  | Html of html_tag
+  | Svg of string
+  | MathML of string
+  | Custom of string
+  | Unknown of string
+
+(** {1 Namespace Constants} *)
+
+val svg_namespace : string
+(** The SVG namespace URI: ["http://www.w3.org/2000/svg"]. *)
+
+val mathml_namespace : string
+(** The MathML namespace URI: ["http://www.w3.org/1998/Math/MathML"]. *)
+
+(** {1 Conversion Functions} *)
+
+val html_tag_of_string_opt : string -> html_tag option
+(** [html_tag_of_string_opt name] converts a lowercase tag name to an [html_tag].
+
+    @param name The lowercase tag name (e.g., ["div"], ["span"])
+    @return [Some tag] if recognized, [None] otherwise
+
+    {b Example:}
+    {[
+      html_tag_of_string_opt "div"  (* Some `Div *)
+      html_tag_of_string_opt "xyz"  (* None *)
+    ]} *)
+
+val is_custom_element_name : string -> bool
+(** [is_custom_element_name name] checks if a name is a valid custom element name.
+
+    A valid custom element name must contain a hyphen and not be reserved
+    (e.g., not start with "xml" or be "annotation-xml").
+
+    @param name The element name to check
+    @return [true] if the name is a valid custom element name *)
+
+val is_svg_namespace : string -> bool
+(** [is_svg_namespace ns] checks if a namespace string represents SVG.
+
+    Accepts both the short form ["svg"] and the full URI. *)
+
+val is_mathml_namespace : string -> bool
+(** [is_mathml_namespace ns] checks if a namespace string represents MathML.
+
+    Accepts both the short form ["mathml"] and the full URI. *)
+
+val tag_of_string : ?namespace:string -> string -> element_tag
+(** [tag_of_string ?namespace name] converts a tag name to an [element_tag].
+
+    @param namespace Optional namespace URI or short form
+    @param name The element name
+    @return The classified element tag
+
+    {b Example:}
+    {[
+      tag_of_string "div"                        (* Html `Div *)
+      tag_of_string ~namespace:"svg" "circle"    (* Svg "circle" *)
+      tag_of_string "my-component"               (* Custom "my-component" *)
+      tag_of_string "xyz"                        (* Unknown "xyz" *)
+    ]} *)
+
+val html_tag_to_string : html_tag -> string
+(** [html_tag_to_string tag] converts an [html_tag] to its lowercase string name.
+
+    @param tag The HTML tag variant
+    @return The lowercase tag name (e.g., ["div"], ["span"]) *)
+
+val tag_to_string : element_tag -> string
+(** [tag_to_string tag] converts any [element_tag] to its string name.
+
+    @param tag The element tag
+    @return The tag name (lowercase for HTML, original case for SVG/MathML) *)
+
+(** {1 Category Predicates} *)
+
+val is_void : html_tag -> bool
+(** [is_void tag] checks if an element is a void element (cannot have children).
+
+    @param tag The HTML tag to check
+    @return [true] if the element is void (br, hr, img, input, etc.) *)
+
+val is_heading : html_tag -> bool
+(** [is_heading tag] checks if an element is a heading element.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is h1-h6 *)
+
+val heading_level : html_tag -> int option
+(** [heading_level tag] gets the heading level (1-6) if applicable.
+
+    @param tag The HTML tag to check
+    @return [Some level] for h1-h6, [None] for other elements *)
+
+val is_sectioning : html_tag -> bool
+(** [is_sectioning tag] checks if an element is sectioning content.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is article, aside, nav, or section *)
+
+val is_sectioning_root : html_tag -> bool
+(** [is_sectioning_root tag] checks if an element is a sectioning root.
+
+    Sectioning roots establish their own outline context.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is blockquote, body, details, dialog,
+            fieldset, figure, or td *)
+
+val is_embedded : html_tag -> bool
+(** [is_embedded tag] checks if an element is embedded content.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is audio, canvas, embed, iframe, img,
+            object, picture, or video *)
+
+val is_interactive : html_tag -> bool
+(** [is_interactive tag] checks if an element is interactive content.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is focusable or activatable *)
+
+val is_form_associated : html_tag -> bool
+(** [is_form_associated tag] checks if an element is form-associated.
+
+    @param tag The HTML tag to check
+    @return [true] if the element can belong to a form *)
+
+val is_labelable : html_tag -> bool
+(** [is_labelable tag] checks if an element can be associated with a label.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is labelable *)
+
+val is_submittable : html_tag -> bool
+(** [is_submittable tag] checks if an element is a submittable form element.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is button, input, select, or textarea *)
+
+val is_resettable : html_tag -> bool
+(** [is_resettable tag] checks if an element is a resettable form element.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is input, output, select, or textarea *)
+
+val is_transparent : html_tag -> bool
+(** [is_transparent tag] checks if an element has a transparent content model.
+
+    Transparent elements inherit their content model from their parent.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is transparent (a, abbr, audio, canvas, etc.) *)
+
+val is_script_supporting : html_tag -> bool
+(** [is_script_supporting tag] checks if an element is script-supporting.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is script or template *)
+
+val is_table_element : html_tag -> bool
+(** [is_table_element tag] checks if an element is a table-related element.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is table, tr, td, th, etc. *)
+
+val is_media : html_tag -> bool
+(** [is_media tag] checks if an element is a media element.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is audio or video *)
+
+val is_list_container : html_tag -> bool
+(** [is_list_container tag] checks if an element is a list container.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is ul, ol, menu, or dl *)
+
+val is_list_item : html_tag -> bool
+(** [is_list_item tag] checks if an element is a list item.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is li, dd, or dt *)
+
+val is_metadata : html_tag -> bool
+(** [is_metadata tag] checks if an element is metadata content.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is base, link, meta, etc. *)
+
+val is_obsolete : html_tag -> bool
+(** [is_obsolete tag] checks if an element is deprecated/obsolete.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is applet, font, marquee, etc. *)
+
+val is_raw_text : html_tag -> bool
+(** [is_raw_text tag] checks if an element is a raw text element.
+
+    Raw text elements contain unparsed text content.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is script or style *)
+
+val is_escapable_raw_text : html_tag -> bool
+(** [is_escapable_raw_text tag] checks if an element is escapable raw text.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is textarea or title *)
+
+val is_phrasing : html_tag -> bool
+(** [is_phrasing tag] checks if an element is phrasing content.
+
+    Phrasing content is inline-level content that forms paragraphs.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is phrasing content *)
+
+val is_flow : html_tag -> bool
+(** [is_flow tag] checks if an element is flow content.
+
+    Flow content is most elements that can appear in the body.
+
+    @param tag The HTML tag to check
+    @return [true] if the element is flow content *)
+
+(** {1 Pattern Matching Helpers} *)
+
+val as_html_tag : element_tag -> html_tag option
+(** [as_html_tag tag] extracts the HTML tag if present.
+
+    @param tag The element tag
+    @return [Some html_tag] if [tag] is [Html html_tag], [None] otherwise *)
+
+val is_html_tag : html_tag -> element_tag -> bool
+(** [is_html_tag expected tag] checks if [tag] matches the expected HTML tag.
+
+    @param expected The expected HTML tag variant
+    @param tag The element tag to check
+    @return [true] if [tag] is [Html expected] *)

lib/htmlrw_check/error_code.ml

···
   | `For_id_mismatch
   | `Role_on_ancestor
   | `Role_on_for
+  | `Aria_label_on_ancestor
   | `Aria_label_on_for
 ]
 
···
   | `Label `For_id_mismatch -> "label-for-mismatch"
   | `Label `Role_on_ancestor -> "role-on-label"
   | `Label `Role_on_for -> "role-on-label"
+  | `Label `Aria_label_on_ancestor -> "aria-label-on-label"
   | `Label `Aria_label_on_for -> "aria-label-on-label"
 
   (* Input errors *)
···
   | `Label `Role_on_for ->
       Printf.sprintf "The %s attribute must not be used on any %s element that is associated with a labelable element."
         (q "role") (q "label")
+  | `Label `Aria_label_on_ancestor ->
+      Printf.sprintf "The %s attribute must not be used on any %s element that is an ancestor of a labelable element."
+        (q "aria-label") (q "label")
   | `Label `Aria_label_on_for ->
       Printf.sprintf "The %s attribute must not be used on any %s element that is associated with a labelable element."
         (q "aria-label") (q "label")

lib/htmlrw_check/error_code.mli

···
         Adding [role] to a label that wraps a form control
         breaks the implicit label association. *)
 
+  | `Aria_label_on_ancestor
+    (** [<label>] with [aria-label] is ancestor of labelable element.
+        [aria-label] on a label that wraps a form control creates
+        conflicting accessible names. *)
+
   | `Role_on_for
     (** [<label>] with role uses [for] association.
         Labels with explicit [for] association must not have [role]. *)

lib/htmlrw_check/semantic/autofocus_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Autofocus attribute validation checker.
+
+    This checker validates that only one element with the [autofocus] attribute
+    exists within each dialog or popover context. HTML5 specifies that there
+    should be at most one autofocused element per autofocus scope.
+
+    {2 Validation Rules}
+
+    - Within each dialog element, only one descendant may have [autofocus]
+    - Within each popover element, only one descendant may have [autofocus]
+    - Nested dialogs and popovers create separate scopes
+
+    {2 Error Messages}
+
+    Reports [Multiple_autofocus] when more than one autofocus attribute is
+    found within the same scope.
+
+    @see <https://html.spec.whatwg.org/multipage/interaction.html#the-autofocus-attribute>
+         HTML Standard: The autofocus attribute
+*)
+
+val checker : Checker.t
+(** The autofocus checker instance.
+
+    This checker can be registered with the checker registry and will be
+    invoked during DOM traversal to validate autofocus attribute usage. *)

lib/htmlrw_check/semantic/lang_detecting_checker.ml

···
 type state = {
   mutable html_lang : string option;
   mutable html_dir : string option;
-  mutable html_locator : (int * int) option;  (* line, column *)
   mutable in_body : bool;
   mutable skip_depth : int;  (* depth in elements to skip *)
   mutable foreign_depth : int;  (* depth in SVG/MathML content to skip *)
-  mutable text_buffer : Buffer.t;
+  text_buffer : Buffer.t;  (* buffer contents are mutated, not the field itself *)
   mutable char_count : int;
 }
 
···
 let create () = {
   html_lang = None;
   html_dir = None;
-  html_locator = None;
   in_body = false;
   skip_depth = 0;
   foreign_depth = 0;
···
 let reset state =
   state.html_lang <- None;
   state.html_dir <- None;
-  state.html_locator <- None;
   state.in_body <- false;
   state.skip_depth <- 0;
   state.foreign_depth <- 0;
   Buffer.clear state.text_buffer;
   state.char_count <- 0
-
-(* Namespaces to skip for language detection *)
-let svg_namespace = "http://www.w3.org/2000/svg"
-let mathml_namespace = "http://www.w3.org/1998/Math/MathML"
-
-let is_foreign_namespace ns =
-  ns = svg_namespace || ns = mathml_namespace
-
-(* Element names that start foreign content (for when namespace isn't set) *)
-let is_foreign_element name =
-  let n = String.lowercase_ascii name in
-  n = "svg" || n = "math"
 
 let get_lang_code lang =
   (* Extract primary language subtag *)
···
   match element.tag with
   | Tag.Html `Html ->
     state.html_lang <- Attr_utils.get_attr "lang" attrs;
-    state.html_dir <- Attr_utils.get_attr "dir" attrs;
-    (* TODO: get line/column from locator *)
-    state.html_locator <- Some (1, 1)
+    state.html_dir <- Attr_utils.get_attr "dir" attrs
   | Tag.Html `Body ->
     state.in_body <- true
   | Tag.Svg _ | Tag.MathML _ ->

lib/htmlrw_check/semantic/lang_detecting_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Language detection and validation checker.
+
+    This checker validates that the document's [lang] attribute matches the
+    detected language of the content, and that the [dir] attribute is correct
+    for right-to-left (RTL) languages.
+
+    {2 Detection Algorithm}
+
+    The checker:
+    1. Collects text content from the document body (up to 30720 characters)
+    2. Skips text from certain elements (scripts, navigation, form controls)
+    3. Skips foreign namespace content (SVG, MathML)
+    4. Uses statistical language detection with >90% confidence threshold
+    5. Handles Traditional vs Simplified Chinese detection
+
+    {2 Validation Rules}
+
+    - Documents should have a [lang] attribute on the [<html>] element
+    - The declared language should match the detected content language
+    - RTL languages (Arabic, Hebrew, Persian, Urdu, etc.) should have [dir="rtl"]
+
+    {2 Error Messages}
+
+    - [Wrong_lang]: The declared language doesn't match detected content
+    - [Missing_dir_rtl]: An RTL language is detected but no [dir] attribute
+    - [Wrong_dir]: The [dir] attribute doesn't match the detected RTL language
+
+    @see <https://html.spec.whatwg.org/multipage/dom.html#the-lang-and-xml:lang-attributes>
+         HTML Standard: The lang attribute
+*)
+
+val checker : Checker.t
+(** The language detection checker instance.
+
+    This checker collects text during DOM traversal and performs language
+    detection at document end. *)

lib/htmlrw_check/semantic/option_checker.ml

···
     (match state.option_stack with
      | ctx :: rest ->
        state.option_stack <- rest;
-       if not ctx.has_text && not ctx.has_label then
+       (* Empty label attribute doesn't count as a valid label *)
+       if not ctx.has_text && (not ctx.has_label || ctx.label_empty) then
          Message_collector.add_typed collector (`Misc `Option_empty_without_label)
      | [] -> ())
   | _ -> ()

lib/htmlrw_check/semantic/option_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Option element validation checker.
+
+    This checker validates that [<option>] elements have proper content or
+    a [label] attribute. Empty options without labels can be confusing for
+    users, especially those using assistive technologies.
+
+    {2 Validation Rules}
+
+    - An [<option>] element must have either:
+      - Non-whitespace text content, OR
+      - A non-empty [label] attribute
+    - Empty [label] attribute values are reported as errors
+    - Options inside [<template>] elements are not checked
+
+    {2 Error Messages}
+
+    - [Option_empty_without_label]: Option has no text and no label attribute
+    - [Bad_value] for label: The label attribute value is empty
+
+    @see <https://html.spec.whatwg.org/multipage/form-elements.html#the-option-element>
+         HTML Standard: The option element
+*)
+
+val checker : Checker.t
+(** The option element checker instance.
+
+    This checker validates option elements during DOM traversal. *)

lib/htmlrw_check/specialized/attr_restrictions_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Attribute restrictions checker.
+
+    This checker validates that certain attributes are not used on elements
+    where they are not allowed. It catches common misuses such as:
+
+    - RDFa-style [href] on elements like [<img>], [<p>], [<div>]
+    - [src] or [media] on [<a>] elements
+    - [srcset] on media elements ([<audio>], [<video>], [<object>])
+
+    {2 Validation Rules}
+
+    The checker maintains a list of (element, disallowed_attributes) pairs
+    for both HTML and SVG elements. When an element is encountered with
+    a disallowed attribute, an error is reported.
+
+    {2 Error Messages}
+
+    Reports [Not_allowed] when an attribute is used on an element where
+    it is not permitted.
+
+    @see <https://html.spec.whatwg.org/multipage/dom.html#element-definitions>
+         HTML Standard: Element definitions
+*)
+
+val checker : Checker.t
+(** The attribute restrictions checker instance. *)

lib/htmlrw_check/specialized/base_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Base element ordering checker.
+
+    This checker validates that the [<base>] element appears before any
+    elements that may use URLs resolved against the base URL. Specifically,
+    [<base>] should appear before [<link>] and [<script>] elements.
+
+    {2 Validation Rules}
+
+    - [<base>] must appear before any [<link>] elements
+    - [<base>] must appear before any [<script>] elements
+    - The order is significant for URL resolution in the document
+
+    {2 Error Messages}
+
+    Reports [Base_after_link_script] when a [<base>] element is found
+    after [<link>] or [<script>] elements.
+
+    @see <https://html.spec.whatwg.org/multipage/semantics.html#the-base-element>
+         HTML Standard: The base element
+*)
+
+val checker : Checker.t
+(** The base element ordering checker instance. *)

lib/htmlrw_check/specialized/datetime_checker.ml

···
 (** Elements that have datetime attribute *)
 let datetime_elements = ["del"; "ins"; "time"]
 
-(** Helper: check if char is digit *)
-let is_digit c = c >= '0' && c <= '9'
-
 (** Parse int safely *)
 let parse_int s =
   try Some (int_of_string s) with _ -> None

lib/htmlrw_check/specialized/datetime_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Datetime attribute validation checker.
+
+    This checker validates the [datetime] attribute on [<del>], [<ins>],
+    and [<time>] elements. The datetime value must conform to a valid
+    date, time, or datetime format as specified by HTML5.
+
+    {2 Supported Formats}
+
+    The checker validates these datetime formats:
+    - Date: [YYYY-MM-DD] (e.g., "2025-12-19")
+    - Month: [YYYY-MM] (e.g., "2025-12")
+    - Year: [YYYY] (e.g., "2025")
+    - Week: [YYYY-Www] (e.g., "2025-W51")
+    - Time: [HH:MM] or [HH:MM:SS] (e.g., "14:30:00")
+    - Datetime: Date followed by time with separator (e.g., "2025-12-19T14:30")
+    - Timezone offsets: [+HH:MM] or [-HH:MM] or [Z]
+    - Duration: [P] prefix followed by duration components
+
+    {2 Validation Rules}
+
+    - Month values must be 01-12
+    - Day values must be valid for the given month
+    - Leap years are correctly handled for February 29th
+    - Hour values must be 00-23
+    - Minute and second values must be 00-59
+    - Week numbers must be 01-53
+
+    {2 Error Messages}
+
+    Reports [Bad_value] when the datetime attribute contains an invalid
+    format or out-of-range values.
+
+    @see <https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#dates-and-times>
+         HTML Standard: Dates and times
+*)
+
+val checker : Checker.t
+(** The datetime attribute checker instance. *)

lib/htmlrw_check/specialized/dl_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** DL element content model validation checker.
+
+    This checker validates that [<dl>] (description list) elements follow
+    the HTML5 content model requirements. Description lists must contain
+    [<dt>] (term) and [<dd>] (description) elements in the correct order.
+
+    {2 Content Model}
+
+    A [<dl>] element may contain:
+    - Zero or more groups of [<dt>] followed by [<dd>] elements
+    - [<div>] elements wrapping [<dt>]/[<dd>] groups (for styling)
+    - [<template>] and [<script>] elements (script-supporting)
+
+    {2 Validation Rules}
+
+    - [<dd>] should not appear before any [<dt>] (terms should come first)
+    - [<dl>] should not be empty (should contain at least one term/description)
+    - When using [<div>] wrappers, mixing wrapped and unwrapped content
+      is discouraged
+    - Each [<div>] in a [<dl>] should contain at least one [<dt>]/[<dd>] group
+
+    {2 Error Messages}
+
+    - [Dl_empty]: The [<dl>] element has no content
+    - [Dd_before_dt]: A [<dd>] appears before any [<dt>] element
+
+    @see <https://html.spec.whatwg.org/multipage/grouping-content.html#the-dl-element>
+         HTML Standard: The dl element
+*)
+
+val checker : Checker.t
+(** The description list content model checker instance. *)

lib/htmlrw_check/specialized/h1_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** H1 element counter and validator.
+
+    This checker warns about multiple [<h1>] elements in a document.
+    While HTML5 technically allows multiple [<h1>] elements when using
+    the document outline algorithm, this algorithm was never implemented
+    by browsers and has been removed from the specification.
+
+    {2 Best Practice}
+
+    Documents should have exactly one [<h1>] element that represents the
+    main heading of the page. Multiple [<h1>] elements can confuse users
+    and assistive technologies about the document's structure.
+
+    {2 Special Cases}
+
+    - [<h1>] elements inside [<svg>] content (e.g., in [<foreignObject>])
+      are not counted, as they may represent different content contexts
+    - The checker reports a warning after the second [<h1>] is encountered
+
+    {2 Error Messages}
+
+    Reports [Multiple_h1] when more than one [<h1>] element is found
+    in the document.
+
+    @see <https://html.spec.whatwg.org/multipage/sections.html#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>
+         HTML Standard: The h1-h6 elements
+*)
+
+val checker : Checker.t
+(** The h1 element counter/validator instance. *)

lib/htmlrw_check/specialized/label_checker.ml

···
     | Tag.Html `Label when state.label_depth = 0 ->
       if state.label_has_role && state.labelable_count > 0 then
         Message_collector.add_typed collector (`Label `Role_on_ancestor);
+      if state.label_has_aria_label && state.labelable_count > 0 then
+        Message_collector.add_typed collector (`Label `Aria_label_on_ancestor);
       state.in_label <- false;
       state.labelable_count <- 0;
       state.label_for_value <- None;

lib/htmlrw_check/specialized/label_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Label element content model validation checker.
+
+    This checker validates that [<label>] elements follow the HTML5
+    content model requirements. Labels associate text with form controls
+    and must be used correctly for accessibility.
+
+    {2 Validation Rules}
+
+    - A [<label>] element may contain at most one labelable element
+      (button, input, meter, output, progress, select, textarea)
+    - When using the [for] attribute, it should reference an existing
+      element ID in the document
+    - Nested labelable elements are not counted (only direct descendants)
+
+    {2 Labelable Elements}
+
+    The following elements can be labeled:
+    - [<button>]
+    - [<input>] (except type="hidden")
+    - [<meter>]
+    - [<output>]
+    - [<progress>]
+    - [<select>]
+    - [<textarea>]
+
+    {2 Error Messages}
+
+    - Multiple labelable elements inside a single [<label>]
+    - [for] attribute references a non-existent ID
+
+    @see <https://html.spec.whatwg.org/multipage/forms.html#the-label-element>
+         HTML Standard: The label element
+*)
+
+val checker : Checker.t
+(** The label element content model checker instance. *)

lib/htmlrw_check/specialized/picture_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Picture element content model and attribute validation checker.
+
+    This checker validates that [<picture>] elements follow the HTML5
+    content model requirements and that attributes are used correctly.
+
+    {2 Content Model}
+
+    A [<picture>] element may contain:
+    - Zero or more [<source>] elements (must come before [<img>])
+    - Exactly one [<img>] element (required)
+    - [<script>] and [<template>] elements (script-supporting)
+
+    {2 Attribute Restrictions}
+
+    The [<picture>] element should not have image-related attributes
+    directly on it (these belong on the [<img>] child):
+    - [src], [srcset], [sizes], [alt], [width], [height]
+    - [crossorigin], [loading], [decoding]
+    - Legacy attributes like [align], [border], [hspace], etc.
+
+    {2 Source Restrictions in Picture}
+
+    When [<source>] is a child of [<picture>]:
+    - It must have [srcset] attribute (required)
+    - It should not have [src] attribute
+
+    {2 Error Messages}
+
+    - Disallowed attributes on [<picture>] or [<source>] in picture context
+    - Invalid parent elements for [<picture>]
+
+    @see <https://html.spec.whatwg.org/multipage/embedded-content.html#the-picture-element>
+         HTML Standard: The picture element
+*)
+
+val checker : Checker.t
+(** The picture element checker instance. *)

lib/htmlrw_check/specialized/ruby_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Ruby element content model validation checker.
+
+    This checker validates that [<ruby>] elements follow the HTML5
+    content model requirements. Ruby annotations are used for East Asian
+    typography to show pronunciation or meaning of characters.
+
+    {2 Content Model}
+
+    A [<ruby>] element must contain:
+    - Phrasing content (the base text)
+    - One or more [<rt>] elements (the ruby text/annotation)
+    - Optional [<rp>] elements (fallback parentheses)
+
+    {2 Validation Rules}
+
+    - [<ruby>] must contain at least one [<rt>] element
+    - There should be phrasing content before the first [<rt>]
+    - [<rp>] elements should surround [<rt>] for fallback rendering
+    - Nested [<ruby>] elements are handled correctly
+
+    {2 Error Messages}
+
+    - Ruby element without any [<rt>] child
+    - Missing base text before ruby annotation
+
+    @see <https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-ruby-element>
+         HTML Standard: The ruby element
+*)
+
+val checker : Checker.t
+(** The ruby element content model checker instance. *)

lib/htmlrw_check/specialized/source_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Source element context validation checker.
+
+    This checker validates that [<source>] element attributes are appropriate
+    for the parent context. The allowed attributes differ based on whether
+    the source is inside [<picture>], [<video>], or [<audio>].
+
+    {2 Context-Dependent Rules}
+
+    In [<picture>] context:
+    - [srcset] is required
+    - [src] is not allowed
+    - [media] and [type] are allowed
+
+    In [<video>] or [<audio>] context:
+    - [src] is required
+    - [srcset] and [sizes] are not allowed
+    - [type] is allowed for MIME type hints
+
+    {2 Error Messages}
+
+    - Missing required attributes for the context
+    - Attributes not allowed in the current context
+
+    @see <https://html.spec.whatwg.org/multipage/embedded-content.html#the-source-element>
+         HTML Standard: The source element
+*)
+
+val checker : Checker.t
+(** The source element context checker instance. *)

lib/htmlrw_check/specialized/srcset_sizes_checker.ml

···
 let split_on_space_respecting_parens s =
   split_respecting_parens ~sep:' ' s |> List.filter (fun s -> s <> "")
 
-(** Check if string contains only whitespace *)
-let is_whitespace_only s =
-  String.for_all (fun c -> c = ' ' || c = '\t' || c = '\n' || c = '\r') s
-
 (** Invalid units that are not CSS lengths but might be confused for them *)
 let invalid_size_units = [
   "deg"; "grad"; "rad"; "turn";  (* angle units *)
···
           NoCommentError
       end
     end
-
-(** For backward compatibility *)
-let has_invalid_css_comment s =
-  match check_css_comment_position s with
-  | NoCommentError -> false
-  | _ -> true
 
 (** Check if scientific notation has invalid exponent (like 1e+1.5 - decimal in exponent) *)
 let has_invalid_scientific_notation s =
···
       end
     end
   end
-
-let has_valid_size_unit size_value =
-  match check_size_value size_value with
-  | Valid -> true
-  | InvalidUnit (_, _) | NegativeValue | CssCommentAfterSign (_, _) | CssCommentBeforeUnit (_, _) | BadScientificNotation | BadCssNumber (_, _) -> false
 
 (** Check if a sizes entry has a media condition (starts with '(') *)
 let has_media_condition entry =

lib/htmlrw_check/specialized/srcset_sizes_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Srcset and sizes attribute validation checker.
+
+    This checker validates the [srcset] and [sizes] attributes on [<img>]
+    and [<source>] elements. These attributes use a specialized microsyntax
+    for responsive images.
+
+    {2 Srcset Syntax}
+
+    The [srcset] attribute contains a comma-separated list of image
+    candidates, each with:
+    - A URL
+    - An optional width descriptor ([Nw], e.g., "800w")
+    - Or an optional pixel density descriptor ([Nx], e.g., "2x")
+
+    Width and pixel density descriptors cannot be mixed in the same srcset.
+
+    {2 Sizes Syntax}
+
+    The [sizes] attribute contains a comma-separated list of:
+    - Media conditions (optional)
+    - Source sizes (CSS lengths)
+
+    The last entry should not have a media condition (it's the default).
+
+    {2 Validation Rules}
+
+    - URLs in srcset must be valid
+    - Width descriptors must be positive integers
+    - Pixel density descriptors must be positive numbers
+    - Sizes must use valid CSS length units
+    - Duplicate descriptors are flagged
+
+    {2 Error Messages}
+
+    - Invalid srcset syntax
+    - Invalid sizes syntax
+    - Missing sizes when srcset uses width descriptors
+    - Invalid CSS length units
+
+    @see <https://html.spec.whatwg.org/multipage/images.html#srcset-attributes>
+         HTML Standard: Srcset attributes
+*)
+
+val checker : Checker.t
+(** The srcset/sizes attribute checker instance. *)

lib/htmlrw_check/specialized/title_checker.ml

···
   mutable in_title : bool;
   mutable title_has_content : bool;
   mutable title_depth : int;
-  mutable is_iframe_srcdoc : bool;
 }
 
 let create () = {
···
   in_title = false;
   title_has_content = false;
   title_depth = 0;
-  is_iframe_srcdoc = false;
 }
 
 let reset state =
···
   state.has_title <- false;
   state.in_title <- false;
   state.title_has_content <- false;
-  state.title_depth <- 0;
-  state.is_iframe_srcdoc <- false
+  state.title_depth <- 0
 
 let start_element state ~element _collector =
   (match element.Element.tag with

lib/htmlrw_check/specialized/title_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Title element validation checker.
+
+    This checker validates that documents have a proper [<title>] element
+    with meaningful content. The title is important for accessibility,
+    SEO, and browser tab identification.
+
+    {2 Validation Rules}
+
+    - Documents should have exactly one [<title>] element in the [<head>]
+    - The [<title>] element should contain non-whitespace text
+    - Empty titles are flagged as errors
+
+    {2 Error Messages}
+
+    - [Empty_title]: The title element is empty or contains only whitespace
+    - [Missing_title]: No title element found in the document head
+
+    @see <https://html.spec.whatwg.org/multipage/semantics.html#the-title-element>
+         HTML Standard: The title element
+*)
+
+val checker : Checker.t
+(** The title element checker instance. *)

lib/htmlrw_check/specialized/unknown_element_checker.ml

···
 (** Unknown HTML element checker.
 
     Detects elements that are not in the HTML5 specification and produces
-    appropriate error messages. Custom elements (with hyphens) are allowed. *)
-
-(** Set of all known HTML5 element names. *)
-let known_elements =
-  let elements = [
-    (* Document metadata *)
-    "html"; "head"; "title"; "base"; "link"; "meta"; "style";
-
-    (* Sections *)
-    "body"; "article"; "section"; "nav"; "aside"; "h1"; "h2"; "h3"; "h4"; "h5"; "h6";
-    "hgroup"; "header"; "footer"; "address"; "main";
-
-    (* Grouping content *)
-    "p"; "hr"; "pre"; "blockquote"; "ol"; "ul"; "menu"; "li"; "dl"; "dt"; "dd";
-    "figure"; "figcaption"; "div";
+    appropriate error messages. Custom elements (with hyphens) are allowed.
 
-    (* Text-level semantics *)
-    "a"; "em"; "strong"; "small"; "s"; "cite"; "q"; "dfn"; "abbr"; "ruby"; "rt"; "rp";
-    "data"; "time"; "code"; "var"; "samp"; "kbd"; "sub"; "sup"; "i"; "b"; "u"; "mark";
-    "bdi"; "bdo"; "span"; "br"; "wbr"; "search";
-
-    (* Edits *)
-    "ins"; "del";
-
-    (* Embedded content *)
-    "picture"; "source"; "img"; "iframe"; "embed"; "object"; "video"; "audio";
-    "track"; "map"; "area"; "math"; "svg";
-
-    (* Tables *)
-    "table"; "caption"; "colgroup"; "col"; "tbody"; "thead"; "tfoot"; "tr"; "td"; "th";
-
-    (* Forms *)
-    "form"; "label"; "input"; "button"; "select"; "datalist"; "optgroup"; "option";
-    "textarea"; "output"; "progress"; "meter"; "fieldset"; "legend";
-
-    (* Interactive *)
-    "details"; "summary"; "dialog";
-
-    (* Scripting *)
-    "script"; "noscript"; "template"; "slot"; "canvas";
-
-    (* Deprecated but still recognized *)
-    "param";
-  ] in
-  let tbl = Hashtbl.create (List.length elements) in
-  List.iter (fun el -> Hashtbl.add tbl el ()) elements;
-  tbl
-
-(** Check if an element name is a custom element (contains hyphen). *)
-let is_custom_element name =
-  String.contains name '-'
-
-(** Check if an element name is known. *)
-let is_known_element name =
-  let name_lower = String.lowercase_ascii name in
-  Hashtbl.mem known_elements name_lower || is_custom_element name_lower
+    Note: Unknown element detection is performed by the parser, which marks
+    unrecognized elements as [Tag.Unknown]. This checker produces appropriate
+    error messages for those elements. *)
 
 type state = {
   mutable stack : string list;  (* Parent element stack *)

lib/htmlrw_check/specialized/unknown_element_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** Unknown HTML element checker.
+
+    This checker detects elements that are not in the HTML5 specification
+    and produces appropriate error messages. Custom elements (names
+    containing hyphens) are allowed per the Web Components specification.
+
+    {2 Recognized Elements}
+
+    The checker recognizes all standard HTML5 elements including:
+    - Document metadata (html, head, title, etc.)
+    - Sections (body, article, section, nav, etc.)
+    - Grouping content (p, div, ul, ol, etc.)
+    - Text-level semantics (a, em, strong, span, etc.)
+    - Embedded content (img, video, audio, iframe, etc.)
+    - Tabular data (table, tr, td, th, etc.)
+    - Forms (form, input, button, select, etc.)
+    - Interactive elements (details, dialog, summary)
+    - Scripting (script, noscript, template)
+
+    {2 Custom Elements}
+
+    Element names containing a hyphen are treated as custom elements
+    and are allowed without warning (e.g., [<my-component>], [<app-header>]).
+
+    {2 Error Messages}
+
+    Reports [Unknown_element] for unrecognized element names that are
+    not valid custom elements.
+
+    @see <https://html.spec.whatwg.org/multipage/custom-elements.html>
+         HTML Standard: Custom elements
+*)
+
+val checker : Checker.t
+(** The unknown element checker instance. *)

lib/htmlrw_check/specialized/url_checker.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** URL validation checker.
+
+    This checker validates URL attributes ([href], [src], [action], etc.)
+    on HTML elements. It checks for common URL issues and security concerns.
+
+    {2 Validated Attributes}
+
+    The checker validates URLs in these attributes:
+    - [href] on [<a>], [<area>], [<base>], [<link>]
+    - [src] on [<audio>], [<embed>], [<iframe>], [<img>], [<input>],
+      [<script>], [<source>], [<track>], [<video>]
+    - [action] on [<form>], [<button>] (formaction)
+    - [cite] on [<blockquote>], [<del>], [<ins>], [<q>]
+    - [data] on [<object>]
+    - [poster] on [<video>]
+    - [value] on [<input type="url">]
+
+    {2 Validation Rules}
+
+    - URLs should be well-formed (parseable)
+    - Relative URLs are allowed
+    - Fragment-only URLs ([#anchor]) are valid
+    - Data URLs are validated for proper structure
+    - javascript: URLs may trigger warnings
+    - Empty URLs are flagged on elements that require them
+
+    {2 Error Messages}
+
+    - [Bad_url]: Malformed URL that cannot be parsed
+    - [Empty_url]: Required URL attribute is empty
+    - Various URL-specific validation errors
+
+    @see <https://url.spec.whatwg.org/>
+         URL Standard
+*)
+
+(** {1 URL Parsing Utilities} *)
+
+val extract_scheme : string -> string option
+(** [extract_scheme url] extracts the scheme (protocol) from a URL.
+
+    @param url The URL to parse
+    @return [Some scheme] if a valid scheme is found (e.g., "http", "https"),
+            [None] if no scheme is present or the URL is relative *)
+
+val validate_url : string -> string -> string -> string option
+(** [validate_url url element_name attr_name] validates a URL.
+
+    Performs comprehensive validation including:
+    - Checking for empty URLs on elements that require them
+    - Validating scheme, host, port, path, query, and fragment
+    - Checking for illegal characters and encoding issues
+    - Validating special schemes (http, https, etc.)
+
+    @param url The URL to validate
+    @param element_name The element containing the URL attribute
+    @param attr_name The attribute name
+    @return [Some error_message] if the URL is invalid, [None] if valid *)
+
+(** {1 Checker} *)
+
+val checker : Checker.t
+(** The URL validation checker instance. *)

lib/htmlrw_check/xhtml_parser.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** XHTML parser using xmlm for proper XML parsing.
+
+    This module provides XML parsing for XHTML files. While the HTML5 parser
+    handles most content, XHTML requires proper XML parsing to correctly handle:
+
+    - Self-closing tags on non-void elements (e.g., [<div/>])
+    - XML namespaces for SVG and MathML
+    - Strict XML well-formedness requirements
+
+    {2 Usage}
+
+    {[
+      if Xhtml_parser.is_xhtml_file (Some "page.xhtml") then
+        match Xhtml_parser.parse_xhtml content with
+        | Ok doc -> (* Process XHTML document *)
+        | Error msg -> (* Handle parse error *)
+    ]}
+*)
+
+(** {1 Types} *)
+
+type xhtml_doc = {
+  root : Html5rw.Dom.node;
+  (** The document root node. *)
+  errors : Html5rw.Error.t list;
+  (** Parse errors (empty for valid XML). *)
+}
+(** An XHTML document representation. *)
+
+(** {1 Parsing} *)
+
+val parse_xhtml : string -> (Html5rw.Dom.node, string) result
+(** [parse_xhtml content] parses XHTML content using xmlm.
+
+    @param content The XHTML content as a string
+    @return [Ok root] with the document root on success,
+            [Error message] with parse error details on failure *)
+
+val is_xhtml_file : string option -> bool
+(** [is_xhtml_file system_id] checks if a system_id indicates an XHTML file.
+
+    @param system_id The optional file path or identifier
+    @return [true] if the path ends with ".xhtml" *)
+
+(** {1 Document Access} *)
+
+val xhtml_root : xhtml_doc -> Html5rw.Dom.node
+(** [xhtml_root doc] returns the document root node. *)
+
+val xhtml_errors : xhtml_doc -> Html5rw.Error.t list
+(** [xhtml_errors doc] returns the parse errors (always empty for XHTML). *)