leptris 1.9.201.0-arm-linux → 1.9.201.2-arm-linux

data/vendor-src/libleptris/src/leptris/xinclude/xinclude.c

@@ -0,0 +1,794 @@
+/* xinclude/xinclude.c — XInclude 1.0 support.
+ *
+ * Implements XInclude 1.0 processing for both parse="text" and
+ * parse="xml" modes.  Walks the document tree, finds xi:include
+ * elements, and substitutes them with the included content.
+ *
+ *   parse="text" — load the file as plain text, splice a text node
+ *                  in place of the xi:include element.
+ *   parse="xml"  — load+parse the file as XML, deep-copy the root
+ *                  of the included document into the parent document's
+ *                  pool, splice the copy in place of the xi:include.
+ *                  xpointer fragment selection is TODO 92 Phase 3.
+ *
+ * XPointer forms (TODO.remaining/04): the xpointer attribute and
+ * href fragment identifiers support bare shorthand (an NCName,
+ * selecting the element with that ID), the element() scheme
+ * (element(name/1/2) child sequences), and the xpointer() scheme
+ * (a full XPath 1.0 expression).  Multiple space-separated schemes
+ * are tried left to right; the first that selects an element wins.
+ * xmlns(prefix=uri) components bind expression prefixes to
+ * namespace URIs for subsequent xpointer() bodies (prefix tests
+ * match by NAMESPACE, whatever prefix the included document
+ * declared).  Non-element selections are treated as
+ * no match (the move path needs an element).
+ *
+ * xi:fallback is honored in both modes.  Element-classification
+ * helpers (is_include_element, etc.) are fully implemented and
+ * documented in leptris.h.
+ */
+
+#include "../../include/leptris.h"
+#include "../leptris_internal.h"
+#include "../dom/element.h"
+#include "../dom/node.h"
+#include "../dom/text.h"
+#include "../dom/cdata.h"
+#include "../dom/comment.h"
+#include "../dom/pi.h"
+#include "../memory/pool.h"
+#include "../encoding/encoding.h"
+#include <string.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+#define XINCLUDE_NAMESPACE "http://www.w3.org/2001/XInclude"
+
+static int element_is_in_xinclude_namespace(LeptrisElement elem) {
+    if (!elem) return 0;
+    const char* ns_uri = leptris_element_get_namespace_uri(elem);
+    if (!ns_uri) return 0;
+    return strcmp(ns_uri, XINCLUDE_NAMESPACE) == 0;
+}
+
+static const char* get_attr_value(LeptrisElement elem, const char* name) {
+    if (!elem || !name) return NULL;
+    struct leptris_attribute* attr = leptris_element_get_attribute_by_name(elem, name);
+    if (!attr) return NULL;
+    return attr_cvalue(attr);
+}
+
+LEPTRIS_API int leptris_xinclude_is_include_element(LeptrisElement elem) {
+    if (!element_is_in_xinclude_namespace(elem)) return 0;
+    const char* name = leptris_element_get_name(elem);
+    return name && strcmp(name, "include") == 0;
+}
+
+LEPTRIS_API int leptris_xinclude_is_fallback_element(LeptrisElement elem) {
+    if (!element_is_in_xinclude_namespace(elem)) return 0;
+    const char* name = leptris_element_get_name(elem);
+    return name && strcmp(name, "fallback") == 0;
+}
+
+LEPTRIS_API const char* leptris_xinclude_get_href(LeptrisElement include_elem) {
+    if (!leptris_xinclude_is_include_element(include_elem)) return NULL;
+    return get_attr_value(include_elem, "href");
+}
+
+LEPTRIS_API const char* leptris_xinclude_get_parse(LeptrisElement include_elem) {
+    if (!leptris_xinclude_is_include_element(include_elem)) return NULL;
+    const char* parse = get_attr_value(include_elem, "parse");
+    return (parse && parse[0]) ? parse : "xml";
+}
+
+LEPTRIS_API const char* leptris_xinclude_get_xpointer(LeptrisElement include_elem) {
+    if (!leptris_xinclude_is_include_element(include_elem)) return NULL;
+    return get_attr_value(include_elem, "xpointer");
+}
+
+LEPTRIS_API const char* leptris_xinclude_get_encoding(LeptrisElement include_elem) {
+    if (!leptris_xinclude_is_include_element(include_elem)) return NULL;
+    return get_attr_value(include_elem, "encoding");
+}
+
+/* ---- parse="text" processor ---- */
+
+/* Load a file into a malloc'd buffer. Returns NULL on failure.
+ * Caller must free the returned buffer. */
+static char* load_file_content(const char* path, size_t* out_len) {
+    if (!path) return NULL;
+    FILE* f = fopen(path, "rb");
+    if (!f) return NULL;
+    fseek(f, 0, SEEK_END);
+    long sz = ftell(f);
+    fseek(f, 0, SEEK_SET);
+    if (sz < 0) { fclose(f); return NULL; }
+    char* buf = (char*)malloc((size_t)sz + 1);
+    if (!buf) { fclose(f); return NULL; }
+    size_t rd = fread(buf, 1, (size_t)sz, f);
+    fclose(f);
+    buf[rd] = '\0';
+    if (out_len) *out_len = rd;
+    return buf;
+}
+
+/* ---- cross-document deep copy ---- */
+
+/* Deep-copy a node subtree into `target_pool`, rewriting every StringView
+ * and char* into freshly pool-owned storage.  The returned subtree is
+ * self-contained — none of its pointers reference the source document.
+ *
+ * Returns NULL on allocation failure (partial copies are abandoned
+ * along with the pool, which is freed document-scoped). */
+static LeptrisNode* deep_copy_node(const LeptrisNode* src,
+                                   LeptrisMemoryPool* target_pool);
+
+static LeptrisElement deep_copy_element(const LeptrisElement src,
+                                        LeptrisMemoryPool* target_pool) {
+    const char* name = leptris_element_get_name(src);
+    LeptrisElement dst = leptris_element_create_pooled(name, target_pool);
+    if (!dst) return NULL;
+
+    /* Copy attributes. */
+    for (struct leptris_attribute* a = leptris_elem_first_attribute(src); a; a = leptris_attr_next(a)) {
+        const char* a_name = attr_cname(a);
+        const char* a_value = attr_cvalue(a);
+        leptris_element_add_attribute_pooled(dst, a_name, a_value, target_pool);
+    }
+
+    /* Copy children (any type).  We can't use leptris_element_append_child
+     * because it only links elements — mixed content needs the generic
+     * set_next_sibling + parent.first_child / last_child wiring. */
+    LeptrisNode* prev_copy = NULL;
+    for (LeptrisNode* child = leptris_elem_first_child(src);
+         child;
+         child = leptris_node_get_next_sibling(child)) {
+
+        LeptrisNode* child_copy = deep_copy_node(child, target_pool);
+        if (!child_copy) return NULL;
+
+        if (prev_copy) {
+            leptris_node_set_next_sibling(prev_copy, child_copy);
+        } else {
+            leptris_elem_set_first_child(dst, child_copy);
+        }
+        prev_copy = child_copy;
+    }
+    if (prev_copy) {
+        leptris_elem_set_last_child(dst, prev_copy);
+    }
+    return dst;
+}
+
+static LeptrisNode* deep_copy_node(const LeptrisNode* src,
+                                   LeptrisMemoryPool* target_pool) {
+    if (!src) return NULL;
+
+    switch (src->type) {
+        case LEPTRIS_NODE_TYPE_ELEMENT:
+            return (LeptrisNode*)deep_copy_element((LeptrisElement)src, target_pool);
+
+        case LEPTRIS_NODE_TYPE_TEXT: {
+            const LeptrisTextNode* t = (const LeptrisTextNode*)src;
+            /* Source text may be borrowed (non-NUL-terminated) — content_len
+             * is authoritative. TODO 115 Phase B. */
+            return (LeptrisNode*)leptris_text_create(t->content, t->content_len, target_pool);
+        }
+
+        case LEPTRIS_NODE_TYPE_CDATA: {
+            const LeptrisCDATANode* c = (const LeptrisCDATANode*)src;
+            const char* content = c->content ? c->content : "";
+            return (LeptrisNode*)leptris_cdata_create(content, strlen(content), target_pool);
+        }
+
+        case LEPTRIS_NODE_TYPE_COMMENT: {
+            const LeptrisCommentNode* cm = (const LeptrisCommentNode*)src;
+            const char* content = cm->content ? cm->content : "";
+            return (LeptrisNode*)leptris_comment_create(content, strlen(content), target_pool);
+        }
+
+        case LEPTRIS_NODE_TYPE_PI: {
+            const LeptrisPINode* pi = (const LeptrisPINode*)src;
+            const char* tgt = pi->target ? pi->target : "";
+            const char* data = pi->data ? pi->data : "";
+            return (LeptrisNode*)leptris_pi_create(tgt, strlen(tgt), data, strlen(data), target_pool);
+        }
+
+        default:
+            /* DOCTYPE and other specialized nodes don't appear in element
+             * content; nothing to copy. */
+            return NULL;
+    }
+}
+
+/* Replace one child of `parent` with `new_node`.
+ * Walks parent->first_child to find the node before `old_node`,
+ * then splices new_node in. */
+static void replace_child_node(LeptrisElement parent,
+                                LeptrisNode* old_node,
+                                LeptrisNode* new_node) {
+    if (!parent || !old_node || !new_node) return;
+
+    LeptrisNode* prev = NULL;
+    LeptrisNode* child = leptris_elem_first_child(parent);
+    while (child && child != old_node) {
+        prev = child;
+        child = leptris_node_get_next_sibling(child);
+    }
+    if (child != old_node) return;  /* old_node not found */
+
+    /* Splice new_node in place of old_node. */
+    LeptrisNode* next = leptris_node_get_next_sibling(old_node);
+    leptris_node_set_next_sibling(new_node, next);
+
+    if (prev) {
+        leptris_node_set_next_sibling(prev, new_node);
+    } else {
+        /* old_node was first_child */
+        leptris_elem_set_first_child(parent, new_node);
+    }
+
+    /* Update last_child if old_node was last. */
+    if (leptris_elem_last_child(parent) == old_node) {
+        leptris_elem_set_last_child(parent, new_node);
+    }
+}
+
+/* Build the full path to an xi:include href relative to base_url.
+ * Writes into out (fixed buffer) and returns out on success, NULL on
+ * overflow.  No dynamic allocation — keeps the call site simple. */
+static char* join_path(char* out, size_t out_size,
+                       const char* base_url, const char* href) {
+    if (!href) return NULL;
+    int n;
+    if (base_url && base_url[0]) {
+        n = snprintf(out, out_size, "%s/%s", base_url, href);
+    } else {
+        n = snprintf(out, out_size, "%s", href);
+    }
+    return (n < 0 || (size_t)n >= out_size) ? NULL : out;
+}
+
+/* Find the xi:fallback child of an xi:include element, if any. */
+static LeptrisElement find_fallback(LeptrisElement include_elem) {
+    for (LeptrisNodeRef fb = leptris_node_first_child((LeptrisNodeRef)include_elem);
+         fb;
+         fb = leptris_node_next_sibling(fb)) {
+        LeptrisElement fe = leptris_node_as_element(fb);
+        if (fe && leptris_xinclude_is_fallback_element(fe)) return fe;
+    }
+    return NULL;
+}
+
+/* Recursion depth cap. Per XInclude spec, the recursion limit is
+ * impl-defined but must be bounded to prevent infinite loops on
+ * mutually-recursive xi:include. 32 is generous; most real-world
+ * inclusion chains are < 5 deep. */
+#define XINCLUDE_MAX_DEPTH 32
+
+/* ---- XPointer evaluation (TODO.remaining/04) ------------------------ */
+
+typedef struct {
+    const char* name;   size_t name_len;  /* scheme name or shorthand token */
+    const char* body;   size_t body_len;  /* inside the parens; empty when none */
+    int  has_parens;
+} XptrComponent;
+
+/* Split an xpointer value into scheme components. Whitespace
+ * separates shorthand tokens; scheme(...) bodies are scanned with
+ * paren-depth so nested parentheses inside xpointer() survive.
+ * Components point into `value` (no allocation). Returns the count
+ * (0 for NULL/empty), or -1 on malformed nesting. */
+static int xptr_parse_components(const char* value, XptrComponent* out,
+                                 int max) {
+    if (!value) return 0;
+    int count = 0;
+    const char* p = value;
+    while (*p) {
+        while (*p == ' ' || *p == '\t') p++;
+        if (!*p) break;
+        const char* start = p;
+        while (*p && *p != '(' && *p != ' ' && *p != '\t') p++;
+        size_t name_len = (size_t)(p - start);
+        if (name_len == 0) return -1;
+        if (*p == '(') {
+            int depth = 1;
+            p++;
+            const char* body = p;
+            while (*p && depth > 0) {
+                if (*p == '(') depth++;
+                else if (*p == ')') depth--;
+                p++;
+            }
+            if (depth != 0) return -1;   /* unbalanced */
+            size_t body_len = (size_t)(p - 1 - body);
+            if (count < max) {
+                out[count].name = start; out[count].name_len = name_len;
+                out[count].body = body;  out[count].body_len = body_len;
+                out[count].has_parens = 1;
+            }
+            count++;
+        } else {
+            /* Bare token: shorthand pointer (an NCName). */
+            if (count < max) {
+                out[count].name = start; out[count].name_len = name_len;
+                out[count].body = NULL;  out[count].body_len = 0;
+                out[count].has_parens = 0;
+            }
+            count++;
+        }
+    }
+    return count;
+}
+
+/* element() scheme body: [NCName]? ('/' integer)+ — walk child
+ * ELEMENTS by 1-based position, starting from the element named by
+ * the shorthand (via id()) or the document element when no name. */
+static LeptrisElement xptr_element_scheme(LeptrisDocument doc,
+                                          const char* body, size_t len) {
+    char* buf = (char*)malloc(len + 1);
+    if (!buf) return NULL;
+    memcpy(buf, body, len);
+    buf[len] = '\0';
+
+    LeptrisElement cur = NULL;
+    const char* p = buf;
+    const char* slash = strchr(p, '/');
+    int first_step_is_document = 0;
+
+    if (slash && slash != p) {
+        /* NCName prefix: shorthand select, then child sequence. */
+        size_t nlen = (size_t)(slash - p);
+        char* name = (char*)malloc(nlen + 32);
+        if (name) {
+            snprintf(name, nlen + 32, "id('%.*s')", (int)nlen, p);
+            LeptrisXPathResult r = leptris_xpath_eval(doc, NULL, name);
+            cur = r ? leptris_xpath_result_get(r, 0) : NULL;
+            if (r) leptris_xpath_result_free(r);
+            free(name);
+        }
+        p = slash;
+    } else if (!slash) {
+        /* element(name): shorthand select, no child sequence. */
+        size_t nlen = len;
+        char* name = (char*)malloc(nlen + 32);
+        if (name) {
+            snprintf(name, nlen + 32, "id('%.*s')", (int)nlen, p);
+            LeptrisXPathResult r = leptris_xpath_eval(doc, NULL, name);
+            cur = r ? leptris_xpath_result_get(r, 0) : NULL;
+            if (r) leptris_xpath_result_free(r);
+            free(name);
+        }
+        free(buf);
+        return cur;
+    } else {
+        /* element(/1/...): the first number selects among the
+         * DOCUMENT's element children -- /1 is the document element
+         * itself; further numbers step into element children. */
+        first_step_is_document = 1;
+    }
+
+    /* Child sequence: /n1/n2/... selecting nth ELEMENT children. */
+    while (p < buf + len) {
+        if (*p != '/') { cur = NULL; break; }
+        p++;
+        if (p >= buf + len || *p < '0' || *p > '9') { cur = NULL; break; }
+        long n = strtol(p, (char**)&p, 10);
+        if (n < 1) { cur = NULL; break; }
+        if (first_step_is_document) {
+            /* The document has exactly one element child; the XPointer
+             * framework only defines /1 at this level. */
+            if (n != 1) { cur = NULL; break; }
+            cur = leptris_document_root(doc);
+            first_step_is_document = 0;
+            continue;
+        }
+        if (!cur) break;
+        LeptrisElement child = leptris_element_first_child_any(cur);
+        long seen = 0;
+        while (child) {
+            seen++;
+            if (seen == n) break;
+            child = leptris_element_next_sibling_any(child);
+        }
+        cur = child;
+    }
+    free(buf);
+    return cur;
+}
+
+/* Parse an xmlns() scheme body: prefix=URI (EscapedURI per the
+ * framework; this subset takes it verbatim). Returns 1 and fills
+ * prefix/uri (malloc'd) on success. */
+static int xptr_xmlns_binding(const char* body, size_t len,
+                              char** prefix, char** uri) {
+    /* Skip leading/trailing whitespace. */
+    while (len > 0 && (body[0] == ' ' || body[0] == '\t')) { body++; len--; }
+    while (len > 0 && (body[len - 1] == ' ' || body[len - 1] == '\t')) len--;
+    const char* eq = memchr(body, '=', len);
+    if (!eq || eq == body) return 0;
+    size_t plen = (size_t)(eq - body);
+    char* p = (char*)malloc(plen + 1);
+    if (!p) return 0;
+    memcpy(p, body, plen);
+    p[plen] = '\0';
+    char* u = (char*)malloc(len - plen);
+    if (!u) { free(p); return 0; }
+    memcpy(u, eq + 1, len - plen - 1);
+    u[len - plen - 1] = '\0';
+    *prefix = p;
+    *uri = u;
+    return 1;
+}
+
+/* Evaluate an xpointer value against the included document.
+ * Returns the first selected ELEMENT, or NULL when nothing (or only
+ * non-elements) matched. Tries schemes left to right per XPointer.
+ * xmlns(prefix=uri) components accumulate bindings (left to right,
+ * per the XPointer framework) that resolve prefixed name tests in
+ * subsequent xpointer() bodies by NAMESPACE, not literal prefix. */
+static LeptrisElement xptr_select(LeptrisDocument doc, const char* value) {
+    XptrComponent comps[8];
+    int n = xptr_parse_components(value, comps, 8);
+    LeptrisXPathNsSet ns = leptris_xpath_ns_set_new();
+    LeptrisElement found = NULL;
+    for (int i = 0; i < n && i < 8 && !found; i++) {
+        const XptrComponent* c = &comps[i];
+        if (c->has_parens && c->name_len == 5 &&
+            strncmp(c->name, "xmlns", 5) == 0) {
+            char *pfx, *u;
+            if (xptr_xmlns_binding(c->body, c->body_len, &pfx, &u)) {
+                leptris_xpath_ns_set_add(ns, pfx, u);
+                free(pfx);
+                free(u);
+            }
+            continue;
+        }
+        if (c->has_parens && c->name_len == 8 &&
+            strncmp(c->name, "xpointer", 8) == 0) {
+            char* expr = (char*)malloc(c->body_len + 1);
+            if (!expr) continue;
+            memcpy(expr, c->body, c->body_len);
+            expr[c->body_len] = '\0';
+            LeptrisXPathResult r = leptris_xpath_eval_ns(doc, NULL, expr, ns);
+            free(expr);
+            if (!r) continue;
+            LeptrisElement e = leptris_xpath_result_get(r, 0);
+            /* Elements only: the ownership-transfer path needs one. */
+            if (e) {
+                /* The element belongs to `doc` (freed by the caller
+                 * after the splice), so freeing the result here is
+                 * safe. */
+                leptris_xpath_result_free(r);
+                found = e;
+                break;
+            }
+            leptris_xpath_result_free(r);
+        } else if (c->has_parens && c->name_len == 7 &&
+                   strncmp(c->name, "element", 7) == 0) {
+            LeptrisElement e = xptr_element_scheme(doc, c->body, c->body_len);
+            if (e) { found = e; break; }
+        } else if (!c->has_parens) {
+            /* Bare token. When it is an NCName it is a shorthand
+             * pointer (the element with that ID). Tokens that are
+             * not NCNames are legacy raw XPath -- the pre-scheme
+             * best-effort behavior, kept for compatibility. */
+            int is_ncname = 1;
+            for (size_t k = 0; k < c->name_len; k++) {
+                char ch = c->name[k];
+                if (ch == '/' || ch == '[' || ch == ']' || ch == '@' ||
+                    ch == '(' || ch == ')' || ch == '=' || ch == '\'' ||
+                    ch == '"' || ch == '*' || ch == '.' || ch == ' ' ||
+                    ch == ':') {
+                    is_ncname = 0;
+                    break;
+                }
+            }
+            char* expr;
+            if (is_ncname) {
+                expr = (char*)malloc(c->name_len + 32);
+                if (!expr) continue;
+                snprintf(expr, c->name_len + 32, "id('%.*s')",
+                         (int)c->name_len, c->name);
+            } else {
+                expr = (char*)malloc(c->name_len + 1);
+                if (!expr) continue;
+                memcpy(expr, c->name, c->name_len);
+                expr[c->name_len] = '\0';
+            }
+            LeptrisXPathResult r = leptris_xpath_eval(doc, NULL, expr);
+            free(expr);
+            if (!r) continue;
+            LeptrisElement e = leptris_xpath_result_get(r, 0);
+            leptris_xpath_result_free(r);
+            if (e) { found = e; break; }
+        }
+        /* Unknown schemes: skipped (lenient subset). */
+    }
+    leptris_xpath_ns_set_free(ns);
+    return found;
+}
+
+/* Forward decl for internal recursion-aware variant. */
+static LeptrisStatus xinclude_process_internal(struct leptris_document* doc,
+                                              const char* base_url,
+                                              int depth);
+
+/* TODO 117 Phase C: cycle detection.
+ *
+ * Each include directive resolves to an absolute path.  We thread a
+ * singly-linked list of `CycleNode` paths through the recursion so we
+ * can reject A -> B -> A without going through the depth guard (which
+ * protects against unbounded recursion, not cycles specifically).
+ *
+ * Memory: each entry is a malloc'd string, freed when the scope ends
+ * (matching push/pop pairing in the recursion). */
+typedef struct CycleNode {
+    char* path;                 /* heap-allocated absolute path */
+    struct CycleNode* next;
+} CycleNode;
+
+static int cycle_contains(CycleNode* ancestors, const char* path) {
+    for (CycleNode* n = ancestors; n; n = n->next) {
+        if (strcmp(n->path, path) == 0) return 1;
+    }
+    return 0;
+}
+
+static CycleNode* cycle_push(CycleNode* ancestors, const char* path) {
+    CycleNode* n = (CycleNode*)malloc(sizeof(CycleNode));
+    if (!n) return ancestors;
+    n->path = strdup(path);
+    n->next = ancestors;
+    if (!n->path) { free(n); return ancestors; }
+    return n;
+}
+
+static CycleNode* cycle_pop(CycleNode* ancestors) {
+    if (!ancestors) return NULL;
+    CycleNode* next = ancestors->next;
+    free(ancestors->path);
+    free(ancestors);
+    return next;
+}
+
+/* Recursive walker. Bottom-up so that included content can itself
+ * contain nested xi:include elements.  Returns 0 on first hard failure
+ * (parse error, alloc failure), 1 otherwise. The `depth` parameter
+ * (TODO 92 Phase 5) tracks how many xi:include layers we've descended
+ * through; XINCLUDE_MAX_DEPTH stops mutual-recursion attacks. */
+static int process_element_xinclude(LeptrisElement elem,
+                                     struct leptris_document* doc,
+                                     const char* base_url,
+                                     int depth,
+                                     CycleNode* ancestors) {
+    if (!elem) return 1;
+
+    LeptrisNodeRef child = leptris_node_first_child((LeptrisNodeRef)elem);
+    while (child) {
+        LeptrisNodeRef next = leptris_node_next_sibling(child);
+        if (leptris_node_get_type(child) == LEPTRIS_NODE_TYPE_ELEMENT) {
+            int rc = process_element_xinclude((LeptrisElement)child, doc,
+                                              base_url, depth, ancestors);
+            if (!rc) return 0;
+        }
+        child = next;
+    }
+
+    if (!leptris_xinclude_is_include_element(elem)) return 1;
+
+    const char* parse = leptris_xinclude_get_parse(elem);
+    const char* href = leptris_xinclude_get_href(elem);
+    if (!href || !href[0]) return 1;
+    const char* xptr_attr = leptris_xinclude_get_xpointer(elem);
+
+    /* XInclude §4: split a fragment identifier off the href. The
+     * fragment (when present) is a shorthand pointer for parse="xml".
+     * Resource errors per spec: fragment + explicit xpointer attr
+     * together, any fragment on parse="text", or an xpointer attr on
+     * parse="text". Resource error -> fallback, like a load failure. */
+    const char* frag = strchr(href, '#');
+    if (frag && !frag[1]) frag = NULL;   /* bare trailing '#' = none */
+    char href_base[4096];
+    size_t base_len = frag ? (size_t)(frag - href) : strlen(href);
+    if (base_len >= sizeof(href_base)) return 1;
+    memcpy(href_base, href, base_len);
+    href_base[base_len] = '\0';
+
+    int is_xml = (!parse || strcmp(parse, "xml") == 0);
+    /* Resource errors per §4 fall through to the fallback handling
+     * below -- an early return here would skip xi:fallback entirely. */
+    int resource_error = 0;
+    if (frag && xptr_attr && xptr_attr[0]) resource_error = 1;
+    if (!is_xml && (frag || (xptr_attr && xptr_attr[0]))) resource_error = 1;
+
+    char full_path[4096];
+    if (!resource_error &&
+        !join_path(full_path, sizeof(full_path), base_url, href_base)) return 1;
+
+    /* TODO 117 Phase C: cycle detection.  If `full_path` is already in
+     * the ancestor chain, we'd be re-including something we're
+     * currently processing -- treat as failure (fallback below). */
+    if (cycle_contains(ancestors, full_path)) {
+        return 0;  /* signal failure so caller (or fallback) handles it */
+    }
+
+    size_t content_len = 0;
+    char* content = resource_error
+                        ? NULL
+                        : load_file_content(full_path, &content_len);
+
+    /* The substitute node — element for parse="xml", text for parse="text",
+     * NULL on failure (fallback path below). */
+    LeptrisNode* substitute = NULL;
+
+    if (content) {
+        if (is_xml) {
+            /* TODO 117 Phase C: push current URI onto ancestor stack so
+             * nested xi:include can detect cycles.  Pop after we're
+             * done with this include (pushed node is the new head;
+             * cycle_pop(ancestors) pops the head). */
+            ancestors = cycle_push(ancestors, full_path);
+
+            LeptrisStatus st = LEPTRIS_OK;
+            LeptrisDocument included_doc = leptris_parse_string(content, content_len, &st);
+            if (included_doc && st == LEPTRIS_OK) {
+                /* Resolve any xi:include nested inside the included doc
+                 * before splicing — XInclude processes recursively.
+                 * Bump depth so mutual-recursion stops at MAX_DEPTH. */
+                xinclude_process_internal(included_doc, base_url, depth + 1);
+                LeptrisElement inc_root = leptris_document_root(included_doc);
+                if (inc_root) {
+                    /* Phase 4 of TODO 92: xpointer attribute selects
+                     * fragment from the included document. The value
+                     * is evaluated as an XPath expression against the
+                     * included doc. If it returns a nodeset, the
+                     * resulting nodes are spliced into the parent
+                     * (replacing the xi:include). Non-nodeset results
+                     * or missing xpointer fall back to the root element.
+                     *
+                     * The XPointer framework also defines scheme-
+                     * qualified forms (xpointer(...), element(/1/2),
+                     * xmlns(...)) which we don't support here — the
+                     * raw attribute value is passed straight to the
+                     * XPath engine as a best-effort implementation. */
+                    /* TODO.remaining/04: the pointer is the xpointer
+                     * attribute (scheme forms) or the href fragment
+                     * (a bare shorthand). The scheme evaluator tries
+                     * xpointer()/element()/shorthand left to right and
+                     * returns an ELEMENT for the move path; a match of
+                     * only non-elements counts as no match. */
+                    const char* xp = (xptr_attr && xptr_attr[0])
+                                         ? xptr_attr
+                                         : (frag ? frag + 1 : NULL);
+                    if (xp && xp[0]) {
+                        LeptrisElement first = xptr_select(included_doc, xp);
+                        if (first) {
+                            /* Move: the fragment still lives in
+                             * included_doc's pool, so we adopt
+                             * included_doc into our lifecycle to keep
+                             * the pool alive. */
+                            leptris_element_set_document_tree(first, doc);
+                            leptris_document_adopt_child(doc, included_doc);
+                            substitute = (LeptrisNode*)first;
+                            included_doc = NULL;
+                        }
+                    }
+                    if (!substitute) {
+                        /* TODO 117 Phase A: pool ownership transfer.
+                         *
+                         * Move (don't copy) the included root into our
+                         * tree.  The child's pool still owns the
+                         * memory, so adopt the child document into
+                         * our lifecycle -- it will be freed when we
+                         * are.  Set included_doc = NULL below the
+                         * adoption to skip the early-exit free. */
+                        included_doc->root = NULL;
+                        if (included_doc->new_dom_root ==
+                            (void*)inc_root) {
+                            included_doc->new_dom_root = NULL;
+                        }
+                        leptris_element_set_document_tree(inc_root, doc);
+                        leptris_document_adopt_child(doc, included_doc);
+                        substitute = (LeptrisNode*)inc_root;
+                        included_doc = NULL;  /* now owned by `doc` */
+                    }
+                }
+            }
+            if (included_doc) leptris_document_free(included_doc);
+            /* TODO 117 Phase C: pop the URI we pushed at the start.
+             * cycle_pop pops the head (the pushed node) and returns
+             * the previous head, restoring ancestors to its pre-push
+             * value. */
+            ancestors = cycle_pop(ancestors);
+        } else if (strcmp(parse, "text") == 0) {
+            /* TODO.remaining/04: the encoding attribute names the
+             * source character set; convert to UTF-8 before splicing.
+             * Only available with iconv; without it the attribute is
+             * ignored (bytes passed through). Failed conversion is a
+             * resource error -> fallback. */
+            const char* enc = get_attr_value(elem, "encoding");
+            if (enc && enc[0] &&
+                strcmp(enc, "UTF-8") != 0 && strcmp(enc, "utf-8") != 0) {
+#if defined(LEPTRIS_HAS_ICONV)
+                size_t conv_len = 0;
+                char* conv = leptris_encoding_convert(
+                    enc, "UTF-8", content, content_len, &conv_len);
+                if (!conv) {
+                    free(content);
+                    content = NULL;   /* resource error -> fallback */
+                    substitute = NULL;
+                    goto fallback;
+                }
+                free(content);
+                content = conv;
+                content_len = conv_len;
+#endif
+            }
+            substitute = (LeptrisNode*)leptris_text_create(content, content_len, doc->pool);
+            /* parse="text" doesn't recurse into another file's body
+             * (no risk of A -> B -> A via text), so no push/pop here. */
+        }
+        /* Unknown parse= value: silently skip, per XInclude spec. */
+        free(content);
+    }
+
+#if defined(LEPTRIS_HAS_ICONV)
+    /* Only referenced by the conversion-failure goto above; without
+     * iconv the goto is compiled out and the label would dangle. */
+fallback:
+#endif
+    if (!substitute) {
+        /* Resource error: try xi:fallback before giving up. */
+        LeptrisElement fb = find_fallback(elem);
+        if (fb) {
+            char* fb_text = leptris_element_get_text_content(fb);
+            if (fb_text) {
+                substitute = (LeptrisNode*)leptris_text_create(fb_text, strlen(fb_text), doc->pool);
+                leptris_free(fb_text);
+            }
+        }
+        /* No fallback: spec says resource error SHOULD be reported; we're
+         * lenient and leave the xi:include in place. */
+    }
+
+    if (substitute) {
+        LeptrisElement parent = leptris_element_get_parent(elem);
+        if (parent) {
+            replace_child_node(parent, (LeptrisNode*)elem, substitute);
+
+            /* The substitute was allocated from doc->pool but its
+             * document pointer (and the document pointers of every
+             * descendant) is still NULL.  Re-stamp them so future
+             * callers can reach the pool through leptris_element_get_document(element). */
+            if (substitute->type == LEPTRIS_NODE_TYPE_ELEMENT) {
+                leptris_element_set_document_tree((LeptrisElement)substitute, doc);
+            }
+        }
+    }
+
+    return 1;
+}
+
+/* Internal recursion-aware variant. Aborts with LEPTRIS_ERROR_INVALID_ARG
+ * if depth exceeds XINCLUDE_MAX_DEPTH (TODO 92 Phase 5). */
+static LeptrisStatus xinclude_process_internal(struct leptris_document* doc,
+                                              const char* base_url,
+                                              int depth) {
+    if (!doc) return LEPTRIS_ERROR_NULL_ARG;
+    if (depth > XINCLUDE_MAX_DEPTH) return LEPTRIS_ERROR_INVALID_ARG;
+
+    LeptrisElement root = leptris_document_root(doc);
+    if (!root) return LEPTRIS_OK;
+
+    /* TODO 117 Phase C: thread empty ancestor list into the walk.
+     * The first include pushes its own URI, so the second visit to the
+     * same URI is detected as a cycle. */
+    int rc = process_element_xinclude(root, doc, base_url, depth, NULL);
+    if (!rc) return LEPTRIS_ERROR_IO;
+    return LEPTRIS_OK;
+}
+
+LEPTRIS_API LeptrisStatus leptris_xinclude_process(LeptrisDocument doc, const char* base_url) {
+    return xinclude_process_internal(doc, base_url, 0);
+}