refactor: simplify public API and isolate native extensions

Separate loop/timer and native interoperability APIs from the portable surface header. Unify dispatch, geometry queries, and timer callbacks; keep framebuffer bookkeeping and frame clocks private, and hide implementation symbols.

Update backends, documentation, examples, and API/integration coverage. Verify exports, strict C/C++ installed consumers, and normal plus ASan/UBSan suites.

2 files changed, 50 insertions, 1 deletions

diff --git a/tests/helpers/check_exports.py b/tests/helpers/check_exports.py
new file mode 100644
index 0000000..0d10014
--- /dev/null
+++ b/tests/helpers/check_exports.py
@@ -0,0 +1,42 @@
+"""Require the shared library to export exactly the public header functions."""
+
+import argparse
+from pathlib import Path
+import re
+import subprocess
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--allow-export', action='append', default=[])
+    parser.add_argument('nm')
+    parser.add_argument('library')
+    parser.add_argument('headers', nargs='+')
+    args = parser.parse_args()
+    declarations = re.compile(
+        r"^[^\n;{}]*\b(yasl_\w+)\s*\([^;{}]*\);", re.MULTILINE
+    )
+    expected = set()
+    for header in args.headers:
+        source = re.sub(r"/\*.*?\*/|//[^\n]*", "", Path(header).read_text(), flags=re.DOTALL)
+        expected.update(declarations.findall(source))
+    if not expected:
+        raise SystemExit("No public function declarations found")
+
+    output = subprocess.check_output(
+        [args.nm, "-D", "--defined-only", "--format=posix", args.library], text=True
+    )
+    exported = {line.split()[0] for line in output.splitlines() if line.strip()}
+    missing = expected - exported
+    leaked = exported - expected - set(args.allow_export)
+    if missing or leaked:
+        if missing:
+            print("Missing public exports:", ", ".join(sorted(missing)))
+        if leaked:
+            print("Unexpected exports:", ", ".join(sorted(leaked)))
+        raise SystemExit(1)
+    print(f"Verified {len(expected)} public exports")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/helpers/run_backends.py b/tests/helpers/run_backends.py
index 9ad9b0d..8c5428a 100644
--- a/tests/helpers/run_backends.py
+++ b/tests/helpers/run_backends.py
@@ -21,7 +21,7 @@ def wait_for(process, ready):
 
 
 def main():
-    weston, xwayland, test = sys.argv[1:]
+    weston, xwayland, test, timers = sys.argv[1:]
     servers = []
     with tempfile.TemporaryDirectory(prefix="yasl-backends-") as directory:
         root = Path(directory)
@@ -73,6 +73,13 @@ def main():
                 run("failure", 2, DISPLAY=":59999")
                 run("failure", 0, WAYLAND_DISPLAY="missing-socket", DISPLAY=":59999")
                 run("mixed")
+                print("Test: Wayland surface timers", flush=True)
+                subprocess.run([timers], env=env, check=True, timeout=8)
+                x_env = env.copy()
+                x_env.pop("WAYLAND_DISPLAY", None)
+                x_env["XDG_SESSION_TYPE"] = "x11"
+                print("Test: X11 surface timers", flush=True)
+                subprocess.run([timers], env=x_env, check=True, timeout=8)
             except BaseException:
                 for log in (wl_log, x_log):
                     log.flush()