feat: zig-xml 0.1.0 — a lenient XML/HTML tokenizer

A small, allocation-light pull tokenizer for untrusted markup: Reader
yields element open/close, text, CDATA, comment, processing-instruction,
and declaration events with names and raw values borrowed from the
input, and decode/decodeInto resolve HTML5 named plus numeric character
references. Unterminated constructs run to end of input rather than
erroring, and there is no DTD or external-entity processing, so it is
safe against XXE and entity-expansion attacks.

The HTML5 named-entity table is vendored from Bun (MIT); see
THIRD_PARTY_NOTICES.md.

Author: chrisbbreuer

.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: mlugg/setup-zig@v2
+        with:
+          version: 0.17.0-dev.1441+d5181a9c9
+      - run: zig fmt --check build.zig src
+      - run: zig build test

.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Create Release
+        uses: stacksjs/action-releaser@v1.2.9
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to Pantry
+        uses: home-lang/pantry/packages/action@main
+        with:
+          publish: zig
+          install: 'false'
+        env:
+          PANTRY_TOKEN: ${{ secrets.PANTRY_TOKEN }}

.gitignore

@@ -0,0 +1,4 @@
+.zig-cache/
+zig-out/
+pantry/
+.DS_Store

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- Lenient, pull-based XML/HTML tokenizer (`Reader`) yielding element
+  open/close, text, CDATA, comment, processing-instruction, and declaration
+  events, borrowing all names and raw values from the input.
+- Quoted, single-quoted, unquoted, and valueless attribute forms.
+- Character-reference decoding (`decode` / `decodeInto`) over the HTML5
+  named-entity table plus decimal and hex numeric references.
+- Unterminated constructs run to end of input without erroring, suiting
+  inspection of hostile or malformed markup.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Breuer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,85 @@
+# zig-xml
+
+A small, lenient, allocation-light **XML/HTML tokenizer** for Zig, with HTML5
+character-reference decoding.
+
+It is a *pull* tokenizer: you call `next()` and get one structural event at a
+time — element open/close, text, CDATA, comments, processing instructions, and
+declarations — with every name and raw value **borrowed from the input**. There
+is no allocation per event (attribute storage is a single reused list), and no
+implicit entity decoding; decoding is a separate, explicit step.
+
+Leniency is deliberate. zig-xml is built to inspect untrusted, possibly
+malformed markup (WAF request bodies, scrapers, editor tooling) the way
+browsers and Go's non-strict `encoding/xml` do — not to validate
+well-formedness. Unterminated constructs run to end of input instead of
+erroring, mismatched close tags are reported verbatim, and unquoted or
+valueless attributes are accepted. It performs no DTD processing and no external
+entity resolution, so it is not exposed to XXE or entity-expansion attacks.
+
+## Install
+
+With [Pantry](https://github.com/home-lang/pantry):
+
+```sh
+pantry add zig-xml
+```
+
+Then add the module in `build.zig`:
+
+```zig
+const xml = b.dependency("xml", .{ .target = target, .optimize = optimize });
+your_module.addImport("xml", xml.module("xml"));
+```
+
+## Usage
+
+```zig
+const std = @import("std");
+const xml = @import("xml");
+
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    const allocator = gpa.allocator();
+
+    var reader = xml.Reader.init(allocator, "<a href=\"?x=1&amp;y=2\">hello</a>");
+    defer reader.deinit();
+
+    while (try reader.next()) |event| switch (event) {
+        .open, .self_closing => |element| {
+            std.debug.print("<{s}>\n", .{element.name});
+            for (element.attributes) |attr| {
+                // Attribute values are raw; decode when you need the text.
+                const value = try xml.decode(allocator, attr.value);
+                defer allocator.free(value);
+                std.debug.print("  {s} = {s}\n", .{ attr.name, value });
+            }
+        },
+        .text => |raw| {
+            const text = try xml.decode(allocator, raw);
+            defer allocator.free(text);
+            std.debug.print("text: {s}\n", .{text});
+        },
+        .close => |name| std.debug.print("</{s}>\n", .{name}),
+        else => {},
+    };
+}
+```
+
+Attribute slices (and the `Element.attributes` list) are valid only until the
+next call to `next()` — copy anything you need to retain.
+
+## API
+
+- `Reader.init(allocator, input) Reader` / `reader.deinit()`
+- `reader.next() !?Event`
+- `Event` — `open` / `self_closing` (`Element`), `close` (name), `text`,
+  `cdata`, `comment`, `processing_instruction`, `declaration`
+- `Element{ name, attributes }`, with `element.attribute(name) ?[]const u8`
+- `decode(allocator, raw) ![]u8` / `decodeInto(&list, allocator, raw) !void`
+- `entity.lookup(name) ?[2]u21` — the underlying HTML5 named-entity table
+
+## License
+
+MIT. The bundled HTML5 named-entity table is vendored from Bun (MIT) — see
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

SECURITY.md

@@ -0,0 +1,17 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities privately to the maintainers via a
+GitHub security advisory on this repository. Do not open a public issue for
+security-sensitive reports.
+
+## Scope
+
+zig-xml is a lenient tokenizer intended to inspect untrusted, possibly hostile
+markup. It performs no allocation per event, runs unterminated constructs to
+end of input rather than erroring, and never executes or resolves external
+entities (there is no DTD processing and no network or file access), so it is
+not subject to XML external-entity (XXE) or billion-laughs entity-expansion
+attacks. Reports of input that causes a crash, unbounded memory growth, or a
+non-terminating loop are in scope.

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,26 @@
+# Third-party notices
+
+## HTML5 named-entity table (`src/entity.zig`)
+
+Vendored from [Bun](https://github.com/oven-sh/bun) `src/md/entity.zig`
+(upstream SHA `fd0b6f1a271fca0b8124b69f230b100f4d636af6`), which is MIT
+licensed. Only the pure, std-only entity data and its binary-search `lookup`
+were taken; no other Bun code is included.
+
+```
+MIT License
+
+Copyright (c) Bun contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
+```

build.zig

@@ -0,0 +1,28 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    // The importable module, exposed to consumers as `xml`.
+    const mod = b.addModule("xml", .{
+        .root_source_file = b.path("src/root.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+
+    const tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/root.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+    const run_tests = b.addRunArtifact(tests);
+    const test_step = b.step("test", "Run unit tests");
+    test_step.dependOn(&run_tests.step);
+
+    const check = b.addTest(.{ .root_module = mod });
+    const check_step = b.step("check", "Compile the public module");
+    check_step.dependOn(&check.step);
+}

build.zig.zon

@@ -0,0 +1,15 @@
+.{
+    .name = .zig_xml,
+    .version = "0.1.0",
+    .minimum_zig_version = "0.17.0-dev.1441+d5181a9c9",
+    .fingerprint = 0x8c46bb51c5b7fc2e, // Changing this has security and trust implications.
+    .paths = .{
+        "README.md",
+        "LICENSE",
+        "SECURITY.md",
+        "THIRD_PARTY_NOTICES.md",
+        "build.zig",
+        "build.zig.zon",
+        "src",
+    },
+}