feat(types): TagifiedTagList/TagifiedTag as real subclasses (#116)

CHANGELOG.md

@@ -9,34 +9,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Breaking changes
 
-* `Tagifiable.tagify()` now returns `Tagified`, a tighter type that
-  excludes the un-resolved `Tagifiable` arm of `TagNode`. Custom
-  `.tagify()` implementations annotated with bare `TagList` or `Tag`
-  return types will fail static type checking; update them to
-  `-> Tagified` (or omit the return annotation). Runtime behavior of
-  correct `.tagify()` implementations is unchanged. (#105)
+* `Tagifiable.tagify()` now returns `Tagified` — a non-generic union
+  that mirrors `TagChild`'s shape (including the flattening
+  conveniences `float`, `None`, `Sequence[Tagified]`) but excludes the
+  un-resolved `Tagifiable` arm. Custom `.tagify()` implementations
+  annotated with bare `TagList` or `Tag` return types will fail
+  static type checking; update them to `-> Tagified` (or omit the
+  return annotation). Runtime behavior of correct implementations is
+  unchanged. (#105, #116, #117)
 
 * `Tag.tagify()` no longer preserves the caller's `Tag` subclass in
   its return type. Code relying on the previous subclass-preserving
   signature should `cast` the result. (#105)
 
+* `TagifiedTagList` is now a real subclass of `TagList["TagifiedNode"]`
+  (previously a `TypeAliasType` alias). `TagifiedTag` is a new parallel
+  subclass of `Tag["TagifiedNode"]`. Both are returned by `.tagify()`
+  and are runtime-`isinstance`-checkable. Their `__init__` / `append`
+  / `extend` / `insert` are statically narrowed to `Tagified`, so
+  pyright flags `tagified.append(SomeTagifiable())` at the call site.
+  The classes stay internal to `htmltools._core` — they are not
+  re-exported from the top-level `htmltools` namespace — so code that
+  wants to `isinstance`-check imports them explicitly from there.
+  Code that depended on `TagifiedTagList` being an alias (e.g.,
+  `typing.get_type_hints` introspection) needs to treat it as a
+  class instead.
+
+  In practice, pyright remains permissive about flowing a
+  `TagifiedTagList` into a parameter typed as bare `TagList` (or
+  `TagList[TagNode]`), so most downstream consumers of `.tagify()`'s
+  return do NOT need migration. (#116)
+
 ### New features
 
 * `Tag` and `TagList` are now generic in their child type, defaulting
-  to `TagNode`. Bare `Tag` / `TagList` retain today's meaning. Mutation
-  methods (`append` / `extend` / `insert`) still accept `Tagifiable` at
-  static-type-check time even on tagified containers — the invariant
-  is enforced at runtime instead (`TagList.tagify()` raises `TypeError`
-  and `get_html_string` raises `RuntimeError` for an un-tagified
-  subtree). See `tests/test_types.py` for the rationale. (#105)
-
-* Added the public type alias `Tagified` — the union of all
-  fully-tagified shapes — for use as the return annotation of
-  `Tagifiable.tagify()` implementations. (#105)
+  to `TagNode`. Bare `Tag` / `TagList` retain today's meaning. (#105)
 
 ### Bug fixes
 
-* `TagList.tagify()` now raises `TypeError` at the boundary when a child's `.tagify()` returns a `TagList` containing an un-tagified `Tagifiable` object. The error names the offending class and slot index so buggy `.tagify()` implementations surface at the source rather than later at render time. The render-time `RuntimeError` raised by `get_html_string()` for an un-tagified child has also been clarified to include the offending class name and a hint that the tree was likely mutated after `.tagify()` was called. (#7, #105, #112)
+* `TagList.tagify()` now defensively normalizes every shape a child's
+  `.tagify()` can return. A return whose contents still include an
+  un-tagified `Tagifiable`, or a return that is itself a bare `Tag` /
+  `TagList` rather than a `TagifiedTag` / `TagifiedTagList`, raises
+  `TypeError` at the boundary, naming the offending class and slot
+  index. (Pyright already rejects these at the call site via the
+  `Tagified` return-type annotation; the runtime guard catches
+  implementations that bypass static checking.) `None` is dropped,
+  `float`/`int` is str-ified, and `Sequence` is flattened —
+  previously these last three shapes either crashed the render path
+  (`None` → `TypeError` in `html_escape`) or silently corrupted the
+  tag tree. The render-time `RuntimeError` raised by
+  `get_html_string()` for an un-tagified child has also been
+  clarified to include the offending class name and a hint that the
+  tree was likely mutated after `.tagify()` was called. (#7, #105,
+  #112, #117)
 
 ### Dependencies