hedron-elements 0.36.0__tar.gz

hedron_elements-0.36.0/.gitignore

@@ -0,0 +1,35 @@
+.DS_Store
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+/build/
+# Artifact/output build trees only — never ignore package source such as
+# packages/hedron/src/hedron/build (Hatchling respects gitignore and would
+# omit it from sdists/wheels; see #32).
+**/.hedron/build/
+packages/hedron-runtime-java/build/
+target/
+.venv*/
+venv*/
+.env
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.tox/
+.nox/
+.audit-build-proj/
+examples/reference-app/.hedron/
+*.html.gz
+/site/
+*.so
+*.dylib
+*.pyd
+.devcontainer/
+# Local SQLite demos (e.g. examples/notes-sqlalchemy)
+*.db

hedron_elements-0.36.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## [0.36.0] — 2026-08-13
+
+- Initial Alpha release: element ABI registry integration, shared bridge, and
+  `hedron-example` reference light-DOM element (RFC-0060 / D-064).

hedron_elements-0.36.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Odos Matthews
+
+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.

hedron_elements-0.36.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.5
+Name: hedron-elements
+Version: 0.36.0
+Summary: Alpha Web Component ABI, shared bridge, and first-party elements for Hedron (RFC-0060)
+Project-URL: Homepage, https://github.com/eddiethedean/hedron
+Project-URL: Repository, https://github.com/eddiethedean/hedron
+Project-URL: Issues, https://github.com/eddiethedean/hedron/issues
+Project-URL: Changelog, https://github.com/eddiethedean/hedron/blob/main/packages/hedron-elements/CHANGELOG.md
+Project-URL: Documentation, https://hedron.readthedocs.io/en/latest/
+Author-email: Odos Matthews <odosmatthews@gmail.com>
+Maintainer-email: Odos Matthews <odosmatthews@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: custom-elements,hedron,htmx,web-components
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.11
+Requires-Dist: hedron-core<0.37,>=0.36.0
+Description-Content-Type: text/markdown
+
+# hedron-elements
+
+**Package maturity:** Alpha · **Train:** `0.36.x` · pin `>=0.36.0,<0.37`
+
+Framework-neutral Web Component ABI, shared HTMX-safe bridge, and the `hedron-example`
+reference element for Hedron (RFC-0060 / D-064).
+
+```bash
+pip install "hedron[elements]>=0.36.0,<0.37"
+# or
+pip install "hedron-elements>=0.36.0,<0.37"
+```
+
+Depends on `hedron-core` only. Host applications do not need Node.js.
+
+See the [implementation plan](https://github.com/eddiethedean/hedron/blob/main/docs/implementation/HEDRON_ELEMENTS_036.md)
+and [platform spec](https://github.com/eddiethedean/hedron/blob/main/docs/implementation/WEB_COMPONENT_PLATFORM.md).

hedron_elements-0.36.0/README.md

@@ -0,0 +1,17 @@
+# hedron-elements
+
+**Package maturity:** Alpha · **Train:** `0.36.x` · pin `>=0.36.0,<0.37`
+
+Framework-neutral Web Component ABI, shared HTMX-safe bridge, and the `hedron-example`
+reference element for Hedron (RFC-0060 / D-064).
+
+```bash
+pip install "hedron[elements]>=0.36.0,<0.37"
+# or
+pip install "hedron-elements>=0.36.0,<0.37"
+```
+
+Depends on `hedron-core` only. Host applications do not need Node.js.
+
+See the [implementation plan](https://github.com/eddiethedean/hedron/blob/main/docs/implementation/HEDRON_ELEMENTS_036.md)
+and [platform spec](https://github.com/eddiethedean/hedron/blob/main/docs/implementation/WEB_COMPONENT_PLATFORM.md).

hedron_elements-0.36.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "hedron-elements"
+version = "0.36.0"
+description = "Alpha Web Component ABI, shared bridge, and first-party elements for Hedron (RFC-0060)"
+readme = "README.md"
+requires-python = ">=3.11,<3.15"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Odos Matthews", email = "odosmatthews@gmail.com" },
+]
+maintainers = [
+    { name = "Odos Matthews", email = "odosmatthews@gmail.com" },
+]
+keywords = [
+    "hedron",
+    "web-components",
+    "htmx",
+    "custom-elements",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "hedron-core>=0.36.0,<0.37",
+]
+
+[project.entry-points."hedron.plugins"]
+hedron_elements = "hedron_elements.plugin:register"
+
+[project.urls]
+Homepage = "https://github.com/eddiethedean/hedron"
+Repository = "https://github.com/eddiethedean/hedron"
+Issues = "https://github.com/eddiethedean/hedron/issues"
+Changelog = "https://github.com/eddiethedean/hedron/blob/main/packages/hedron-elements/CHANGELOG.md"
+Documentation = "https://hedron.readthedocs.io/en/latest/"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hedron_elements"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/hedron_elements/static/hedron-bridge.mjs" = "hedron_elements/static/hedron-bridge.mjs"
+"src/hedron_elements/static/hedron-example.mjs" = "hedron_elements/static/hedron-example.mjs"
+"src/hedron_elements/static/hedron-example.css" = "hedron_elements/static/hedron-example.css"
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "src/hedron_elements",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "pyproject.toml",
+]

hedron_elements-0.36.0/src/hedron_elements/__init__.py

@@ -0,0 +1,22 @@
+"""hedron-elements: Alpha Web Component ABI and first-party elements."""
+
+from __future__ import annotations
+
+from hedron_elements.example import Example
+from hedron_elements.markup import render_element_markup
+from hedron_elements.state import (
+    OwnershipMode,
+    apply_incoming_update,
+    validate_field_ownership,
+)
+
+__version__ = "0.36.0"
+
+__all__ = [
+    "Example",
+    "OwnershipMode",
+    "apply_incoming_update",
+    "render_element_markup",
+    "validate_field_ownership",
+    "__version__",
+]

hedron_elements-0.36.0/src/hedron_elements/assets.py

@@ -0,0 +1,26 @@
+"""Locate packaged element static assets."""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+__all__ = ["asset_path", "bridge_path", "example_css_path", "example_module_path"]
+
+
+def asset_path(name: str) -> Path:
+    target = resources.files("hedron_elements").joinpath("static").joinpath(name)
+    with resources.as_file(target) as path:
+        return Path(path)
+
+
+def bridge_path() -> Path:
+    return asset_path("hedron-bridge.mjs")
+
+
+def example_module_path() -> Path:
+    return asset_path("hedron-example.mjs")
+
+
+def example_css_path() -> Path:
+    return asset_path("hedron-example.css")

hedron_elements-0.36.0/src/hedron_elements/example.py

@@ -0,0 +1,81 @@
+"""Reference light-DOM element: hedron-example."""
+
+from __future__ import annotations
+
+from hedron_core.component import Component, NodeLike
+from hedron_core.html import html
+from hedron_core.models import Props
+from hedron_core.registry import ElementFieldOwnership
+from hedron_elements.markup import render_element_markup
+
+ABI_VERSION = 1
+TAG_NAME = "hedron-example"
+ELEMENT_ID = "hedron-example"
+
+
+class ExampleProps(Props):
+    status: str = "Ready"
+    class_: str | None = None
+
+
+class Example(Component[ExampleProps]):
+    """ABI probe with controlled status text and disposable local UI."""
+
+    props_type = ExampleProps
+    logical_name = "Example"
+    distribution = "hedron-elements"
+
+    def __init__(
+        self,
+        status: str = "Ready",
+        *,
+        class_: str | None = None,
+        **kwargs: object,
+    ) -> None:
+        super().__init__(ExampleProps(status=status, class_=class_, **kwargs))
+
+    def render(self) -> NodeLike:
+        return html.tag(TAG_NAME)(
+            html.p(self.props.status, **{"data-hedron-server-region": "content"}),
+            html.button("Details", type="button", **{"data-hedron-local": "toggle"}),
+            html.div(
+                "Local-only panel (disposable).",
+                hidden=True,
+                **{"data-hedron-local": "panel"},
+            ),
+            **{
+                "data-hedron-abi": str(ABI_VERSION),
+                "data-hedron-element": ELEMENT_ID,
+                "status": self.props.status,
+                "class_": self.props.class_,
+            },
+        )
+
+    def render_markup(self) -> str:
+        return render_element_markup(
+            tag_name=TAG_NAME,
+            abi_version=ABI_VERSION,
+            element_id=ELEMENT_ID,
+            attributes={"status": self.props.status},
+            server_content=self.props.status,
+        )
+
+
+EXAMPLE_OWNERSHIP: tuple[ElementFieldOwnership, ...] = (
+    ElementFieldOwnership(
+        name="status",
+        mode="controlled",
+        reflection="attribute",
+        incoming_update="replace",
+        persistence="none",
+        event="hedron-example-change",
+    ),
+    ElementFieldOwnership(
+        name="expanded",
+        mode="local",
+        reflection="none",
+        incoming_update="preserve",
+        persistence="none",
+        event="hedron-example-change",
+    ),
+)

hedron_elements-0.36.0/src/hedron_elements/markup.py

@@ -0,0 +1,171 @@
+"""Frozen element markup helpers (ABI-036)."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from html import escape
+from typing import Any
+
+from hedron_core.diagnostics import error
+
+__all__ = [
+    "MAX_STRUCTURED_BYTES",
+    "MAX_STRUCTURED_DEPTH",
+    "MAX_STRUCTURED_ITEMS",
+    "encode_structured_input",
+    "render_element_markup",
+]
+
+MAX_STRUCTURED_BYTES = 8192
+MAX_STRUCTURED_ITEMS = 64
+MAX_STRUCTURED_DEPTH = 4
+
+# Custom-element token: no quotes, spaces, ``>``, or ``/`` breakouts (#215).
+_CUSTOM_ELEMENT_TAG = re.compile(r"^[a-z][a-z0-9]*(-[a-z0-9]+)+$")
+# Match hedron_core.html / _serializer attribute-name allowlist.
+_SAFE_ATTR_NAME = re.compile(r"^[A-Za-z_][\w.-]*$")
+_FROZEN_ATTR_NAMES = frozenset(
+    {
+        "data-hedron-abi",
+        "data-hedron-element",
+        "data-hedron-input",
+    }
+)
+
+
+def _strip_nul(value: str) -> str:
+    return value.replace("\x00", "")
+
+
+def _require_element_tag(tag_name: str) -> str:
+    tag = _strip_nul(tag_name).strip().lower()
+    if not _CUSTOM_ELEMENT_TAG.match(tag) or not tag.startswith("hedron-"):
+        raise error(
+            "HED-ELEMENT-0003",
+            title="Invalid element tag",
+            explanation=f"Tag {tag_name!r} is not a valid first-party element name.",
+            remediation="Use a hedron-* custom element tag matching [a-z][a-z0-9]*(-[a-z0-9]+)+.",
+        )
+    return tag
+
+
+def _require_safe_attr_name(name: str) -> str:
+    cleaned = _strip_nul(name)
+    if not cleaned or not _SAFE_ATTR_NAME.match(cleaned) or any(ord(ch) < 32 for ch in cleaned):
+        raise error(
+            "HED-SEC-0010",
+            title="Unsafe attribute name rejected",
+            explanation=f"Attribute name {name!r} contains forbidden characters.",
+            remediation="Use token attribute names matching [A-Za-z_][\\w.-]*.",
+        )
+    lower = cleaned.lower()
+    if lower.startswith("on"):
+        raise error(
+            "HED-SEC-0002",
+            title="Inline event handler rejected",
+            explanation=f"Attribute {name!r} is an inline event handler.",
+            remediation="Use HTMX attributes or registered Web Components instead.",
+        )
+    return cleaned
+
+
+def _depth(value: object, current: int = 0) -> int:
+    if current > MAX_STRUCTURED_DEPTH:
+        return current
+    if isinstance(value, Mapping):
+        return max((_depth(v, current + 1) for v in value.values()), default=current)
+    if isinstance(value, (list, tuple)):
+        return max((_depth(v, current + 1) for v in value), default=current)
+    return current
+
+
+def encode_structured_input(payload: Mapping[str, Any], *, instance_id: str) -> str:
+    """Return an inert JSON script tag associated by instance id (never executed)."""
+    try:
+        raw = json.dumps(payload, separators=(",", ":"), allow_nan=False)
+    except (TypeError, ValueError) as exc:
+        raise error(
+            "HED-ELEMENT-0005",
+            title="Structured input encoding failed",
+            explanation=str(exc),
+            remediation="Provide JSON-serializable bounded configuration.",
+        ) from exc
+    if len(raw.encode("utf-8")) > MAX_STRUCTURED_BYTES:
+        raise error(
+            "HED-ELEMENT-0005",
+            title="Structured input too large",
+            explanation=f"Payload exceeds {MAX_STRUCTURED_BYTES} bytes.",
+            remediation="Move large datasets to page/job endpoints.",
+        )
+    if isinstance(payload, Mapping) and len(payload) > MAX_STRUCTURED_ITEMS:
+        raise error(
+            "HED-ELEMENT-0005",
+            title="Structured input item limit",
+            explanation=f"Payload exceeds {MAX_STRUCTURED_ITEMS} items.",
+            remediation="Reduce configuration size.",
+        )
+    if _depth(payload) > MAX_STRUCTURED_DEPTH:
+        raise error(
+            "HED-ELEMENT-0005",
+            title="Structured input depth limit",
+            explanation=f"Payload exceeds depth {MAX_STRUCTURED_DEPTH}.",
+            remediation="Flatten configuration.",
+        )
+    safe_id = escape(_strip_nul(instance_id), quote=True)
+    # Escape closing tags inside JSON text nodes.
+    safe_json = raw.replace("<", "\\u003c").replace(">", "\\u003e").replace("&", "\\u0026")
+    return f'<script type="application/json" data-hedron-input-for="{safe_id}">{safe_json}</script>'
+
+
+def render_element_markup(
+    *,
+    tag_name: str,
+    abi_version: int,
+    element_id: str,
+    attributes: Mapping[str, str] | None = None,
+    server_content: str = "",
+    instance_id: str | None = None,
+    structured_input: Mapping[str, Any] | None = None,
+) -> str:
+    """Render frozen ABI markup for a light-DOM first-party element."""
+    tag = _require_element_tag(tag_name)
+    if abi_version < 1:
+        raise error(
+            "HED-ELEMENT-0002",
+            title="Invalid ABI version",
+            explanation=f"ABI {abi_version} is unsupported.",
+            remediation="Use a positive ABI major.",
+        )
+    # Caller attributes first; frozen ABI identity always wins afterward (#215).
+    attrs: dict[str, str] = {}
+    for key, value in dict(attributes or {}).items():
+        safe_key = _require_safe_attr_name(str(key))
+        if safe_key.lower() in _FROZEN_ATTR_NAMES:
+            raise error(
+                "HED-ELEMENT-0003",
+                title="Frozen element attribute rejected",
+                explanation=f"Attribute {safe_key!r} is reserved for ABI identity markup.",
+                remediation="Omit data-hedron-abi / data-hedron-element / data-hedron-input.",
+            )
+        attrs[safe_key] = _strip_nul(str(value))
+    attrs["data-hedron-abi"] = str(abi_version)
+    attrs["data-hedron-element"] = _strip_nul(element_id)
+    if instance_id:
+        attrs["data-hedron-input"] = _strip_nul(instance_id)
+    attr_html = " ".join(
+        f'{escape(k, quote=True)}="{escape(str(v), quote=True)}"' for k, v in attrs.items()
+    )
+    content = escape(_strip_nul(server_content))
+    body = f'<{tag} {attr_html}><p data-hedron-server-region="content">{content}</p></{tag}>'
+    if structured_input is not None:
+        if not instance_id:
+            raise error(
+                "HED-ELEMENT-0005",
+                title="Structured input requires instance id",
+                explanation="data-hedron-input association is required.",
+                remediation="Pass instance_id with structured_input.",
+            )
+        body = encode_structured_input(structured_input, instance_id=instance_id) + body
+    return body

hedron_elements-0.36.0/src/hedron_elements/plugin.py

@@ -0,0 +1,141 @@
+"""Register hedron-elements plugin: ABI, assets, Example component."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from hedron_core.identifiers import content_digest
+from hedron_core.plugins import PluginCapabilities, PluginContext, PluginMeta
+from hedron_core.registry import (
+    register_asset,
+    register_browser_module,
+    register_component,
+    register_element_definition,
+)
+from hedron_elements.example import (
+    ABI_VERSION,
+    ELEMENT_ID,
+    EXAMPLE_OWNERSHIP,
+    TAG_NAME,
+    Example,
+)
+
+_ROOT = Path(__file__).resolve().parent
+_BRIDGE = _ROOT / "static" / "hedron-bridge.mjs"
+_JS = _ROOT / "static" / "hedron-example.mjs"
+_CSS = _ROOT / "static" / "hedron-example.css"
+
+PLUGIN_META = PluginMeta(
+    name="hedron_elements",
+    version="0.36.0",
+    distribution="hedron-elements",
+    hedron_version=">=0.36,<0.37",
+    capabilities=PluginCapabilities(
+        python=True,
+        styles=True,
+        assets=True,
+        browser_js=True,
+        explorer_panels=False,
+    ),
+)
+
+
+def register(ctx: PluginContext) -> None:
+    logical = (
+        f"{Example.distribution}:{Example.__module__}."
+        f"{getattr(Example, 'logical_name', Example.__name__)}"
+    )
+    register_component(
+        logical_id=logical,
+        name=getattr(Example, "logical_name", Example.__name__) or Example.__name__,
+        module=Example.__module__,
+        distribution=Example.distribution,
+        props_model=Example.props_type.__name__,
+        browser_modules=(str(_JS),) if _JS.is_file() else (),
+        accessibility_notes=(
+            "Light-DOM status region with progressive-enhancement toggle; "
+            "usable before upgrade and after module failure."
+        ),
+    )
+
+    if _BRIDGE.is_file():
+        digest = content_digest(_BRIDGE.read_bytes())
+        register_asset(
+            logical_id="hedron-elements:bridge.mjs",
+            kind="module",
+            path=str(_BRIDGE),
+            digest=digest,
+            content_type="text/javascript",
+        )
+    if _JS.is_file():
+        digest = content_digest(_JS.read_bytes())
+        register_asset(
+            logical_id="hedron-elements:example.mjs",
+            kind="module",
+            path=str(_JS),
+            digest=digest,
+            content_type="text/javascript",
+        )
+        register_browser_module(
+            logical_id="hedron-elements:example",
+            tag_name=TAG_NAME,
+            module_path=str(_JS),
+            observed_attributes=("status", "data-hedron-abi", "data-hedron-element"),
+            events=("hedron-example-change",),
+            shadow_dom=False,
+            htmx_lifecycle=True,
+        )
+        register_element_definition(
+            logical_id=ELEMENT_ID,
+            tag_name=TAG_NAME,
+            abi_version=ABI_VERSION,
+            module_asset_id="hedron-elements:example.mjs",
+            attributes=("status", "data-hedron-abi", "data-hedron-element"),
+            state_ownership=EXAMPLE_OWNERSHIP,
+            events=("hedron-example-change",),
+            dom_policy="light",
+            server_regions=("content",),
+            form_contract=None,
+            a11y_contract={
+                "role": "group",
+                "name": "Example status",
+                "keyboard": "button toggle",
+            },
+            style_contract={"tokens": "hedron-*"},
+            resources=("hedron-elements:bridge.mjs", "hedron-elements:example.css"),
+            lifecycle={
+                "connect": "idempotent",
+                "disconnect": "abort+dispose",
+                "htmx": "beforeCleanupElement",
+            },
+            fallback={
+                "pre_upgrade": "server content visible",
+                "js_off": "server content visible",
+                "module_failure": "retain server content",
+            },
+            first_party=True,
+        )
+    if _CSS.is_file():
+        digest = content_digest(_CSS.read_bytes())
+        register_asset(
+            logical_id="hedron-elements:example.css",
+            kind="css",
+            path=str(_CSS),
+            digest=digest,
+            content_type="text/css",
+        )
+
+    ctx.register_diagnostic_owner("HED-ELEMENT-")
+    ctx.register_feature(
+        name="web_component_abi",
+        stability="experimental",
+        description="Versioned element ABI, SSR fallback, and HTMX lifecycle foundation.",
+        http_fallback=True,
+        security_notes=(
+            "Custom-element events are untrusted; Shadow DOM is not a security boundary; "
+            "CSRF/authz remain server-owned."
+        ),
+    )
+
+
+register.PLUGIN_META = PLUGIN_META  # type: ignore[attr-defined]

hedron_elements-0.36.0/src/hedron_elements/state.py

@@ -0,0 +1,113 @@
+"""ElementStateOwnership helpers (STATE-036)."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from hedron_core.diagnostics import error
+from hedron_core.registry import ElementFieldOwnership
+
+OwnershipMode = Literal["controlled", "local", "draft", "preference"]
+IncomingPolicy = Literal["replace", "preserve", "rebase", "conflict"]
+
+_CAPABILITY_FIELDS = frozenset(
+    {
+        "auth",
+        "authorization",
+        "csrf",
+        "secret",
+        "token",
+        "capability",
+        "trusted_html",
+        "tenant",
+    }
+)
+
+__all__ = [
+    "IncomingPolicy",
+    "OwnershipMode",
+    "apply_incoming_update",
+    "refuse_transfer",
+    "validate_field_ownership",
+]
+
+
+def validate_field_ownership(field: ElementFieldOwnership) -> ElementFieldOwnership:
+    if field.mode not in {"controlled", "local", "draft", "preference"}:
+        raise error(
+            "HED-ELEMENT-STATE-0001",
+            title="Unknown ownership mode",
+            explanation=f"Field {field.name!r} has invalid mode {field.mode!r}.",
+            remediation="Use controlled, local, draft, or preference.",
+        )
+    lowered = field.name.lower()
+    if any(token in lowered for token in _CAPABILITY_FIELDS) and field.mode != "controlled":
+        raise error(
+            "HED-ELEMENT-STATE-0002",
+            title="Illegal element-owned capability",
+            explanation=f"Field {field.name!r} cannot use mode {field.mode!r}.",
+            remediation="Keep capabilities under server-controlled ownership.",
+        )
+    if field.persistence not in {"none", "preference", "draft"}:
+        raise error(
+            "HED-ELEMENT-STATE-0002",
+            title="Illegal persistence policy",
+            explanation=f"Persistence {field.persistence!r} is not allowed.",
+            remediation="Use none, preference, or draft persistence.",
+        )
+    if field.persistence == "preference" and field.mode != "preference":
+        raise error(
+            "HED-ELEMENT-STATE-0002",
+            title="Illegal persistence for ownership mode",
+            explanation="Only preference fields may persist as preference.",
+            remediation="Align persistence with ownership mode.",
+        )
+    return field
+
+
+def apply_incoming_update(
+    *,
+    mode: OwnershipMode,
+    dirty: bool,
+    policy: IncomingPolicy | None,
+    allow_rebase: bool = False,
+) -> IncomingPolicy:
+    """Resolve dirty-draft / controlled incoming-update policy (no silent LWW)."""
+    if mode == "local":
+        return "preserve"
+    if mode == "controlled":
+        return "replace"
+    if mode == "preference":
+        return policy or "preserve"
+    # draft
+    if not dirty:
+        return "replace"
+    chosen = policy or "conflict"
+    if chosen == "rebase" and not allow_rebase:
+        raise error(
+            "HED-ELEMENT-STATE-0004",
+            title="Unproven draft rebase",
+            explanation="Rebase requires a proven typed merge.",
+            remediation="Use conflict, preserve, or a proven rebase.",
+        )
+    if chosen not in {"replace", "preserve", "rebase", "conflict"}:
+        raise error(
+            "HED-ELEMENT-STATE-0004",
+            title="Missing draft incoming policy",
+            explanation=f"Policy {chosen!r} is not supported.",
+            remediation="Declare replace, preserve, rebase, or conflict.",
+        )
+    if chosen == "conflict":
+        # Explicit conflict path — never last-write-wins.
+        return "conflict"
+    return chosen
+
+
+def refuse_transfer() -> None:
+    """Cross-instance draft transfer is out of scope until phase 0.40."""
+    raise error(
+        "HED-ELEMENT-STATE-0006",
+        title="Draft transfer not available",
+        explanation="Cross-instance draft transfer is deferred to phase 0.40.",
+        remediation="Keep draft state instance-local until STATE-040.",
+    )

hedron_elements-0.36.0/src/hedron_elements/static/hedron-bridge.mjs

@@ -0,0 +1,60 @@
+/**
+ * Shared Hedron element bridge (phase 0.36).
+ * Owns early HTMX cleanup hooks and typed-event allowlisting.
+ * Keep gzip size ≤ 12 KiB.
+ */
+const OWNED = new WeakMap();
+
+export function track(el, resources) {
+  const bag = OWNED.get(el) || { ac: null, listeners: [], timers: [] };
+  if (!bag.ac) bag.ac = new AbortController();
+  OWNED.set(el, bag);
+  if (resources?.listener) bag.listeners.push(resources.listener);
+  if (resources?.timer != null) bag.timers.push(resources.timer);
+  return bag.ac.signal;
+}
+
+export function dispose(el) {
+  const bag = OWNED.get(el);
+  if (!bag) return;
+  try {
+    bag.ac?.abort();
+  } catch (_) {}
+  for (const t of bag.timers || []) clearTimeout(t);
+  bag.timers = [];
+  bag.listeners = [];
+  OWNED.delete(el);
+}
+
+export function validateEventDetail(detail, schemaKeys) {
+  if (detail == null || typeof detail !== "object") return false;
+  if ("__proto__" in detail || "constructor" in Object.getOwnPropertyDescriptors(detail || {})) {
+    // still allow normal objects; reject dangerous keys
+  }
+  for (const key of Object.keys(detail)) {
+    if (schemaKeys && !schemaKeys.includes(key)) return false;
+    const v = detail[key];
+    if (typeof v === "function") return false;
+    if (typeof Node !== "undefined" && v instanceof Node) return false;
+  }
+  return true;
+}
+
+function onBeforeCleanup(ev) {
+  const root = ev?.detail?.elt || ev?.target;
+  if (!root) return;
+  if (root.tagName && String(root.tagName).toLowerCase().startsWith("hedron-")) {
+    dispose(root);
+  }
+  root.querySelectorAll?.("[data-hedron-element]").forEach((node) => dispose(node));
+}
+
+if (typeof document !== "undefined") {
+  document.body?.addEventListener?.("htmx:beforeCleanupElement", onBeforeCleanup);
+  document.addEventListener("htmx:beforeSwap", (ev) => {
+    const t = ev.target || document;
+    t.querySelectorAll?.("[data-hedron-element]").forEach((node) => dispose(node));
+  });
+}
+
+export const HEDRON_BRIDGE_VERSION = 1;

hedron_elements-0.36.0/src/hedron_elements/static/hedron-example.css

@@ -0,0 +1,10 @@
+hedron-example {
+  display: block;
+  border: 1px solid var(--hedron-border, #ccc);
+  padding: 0.75rem;
+  border-radius: 0.25rem;
+}
+hedron-example [data-hedron-local="panel"] {
+  margin-top: 0.5rem;
+  color: var(--hedron-muted, #555);
+}

hedron_elements-0.36.0/src/hedron_elements/static/hedron-example.mjs

@@ -0,0 +1,110 @@
+/**
+ * hedron-example — 0.36 ABI probe (light DOM).
+ * Controlled `status` + disposable local expanded UI. Not form-associated.
+ */
+import { dispose, track, validateEventDetail } from "./hedron-bridge.mjs";
+
+const TAG = "hedron-example";
+const EVENT = "hedron-example-change";
+
+class HedronExample extends HTMLElement {
+  static observedAttributes = ["status", "data-hedron-abi"];
+
+  #signal = null;
+  #onToggle = null;
+  #expanded = false;
+
+  connectedCallback() {
+    this.#ensure();
+    this.#signal = track(this);
+    this.#bind();
+    this.#sync();
+    this.setAttribute("data-hedron-upgraded", "true");
+  }
+
+  disconnectedCallback() {
+    this.#unbind();
+    dispose(this);
+    this.#signal = null;
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) this.#sync();
+  }
+
+  #ensure() {
+    if (!this.querySelector(":scope > [data-hedron-server-region='content']")) {
+      const p = document.createElement("p");
+      p.setAttribute("data-hedron-server-region", "content");
+      p.textContent = this.getAttribute("status") || "Ready";
+      this.appendChild(p);
+    }
+    if (!this.querySelector(":scope > [data-hedron-local='toggle']")) {
+      const btn = document.createElement("button");
+      btn.type = "button";
+      btn.setAttribute("data-hedron-local", "toggle");
+      btn.textContent = "Details";
+      this.appendChild(btn);
+    }
+    if (!this.querySelector(":scope > [data-hedron-local='panel']")) {
+      const panel = document.createElement("div");
+      panel.setAttribute("data-hedron-local", "panel");
+      panel.hidden = true;
+      panel.textContent = "Local-only panel (disposable).";
+      this.appendChild(panel);
+    }
+  }
+
+  #unbind() {
+    const btn = this.querySelector(":scope > [data-hedron-local='toggle']");
+    if (btn && this.#onToggle) btn.removeEventListener("click", this.#onToggle);
+    this.#onToggle = null;
+  }
+
+  #bind() {
+    this.#unbind();
+    const btn = this.querySelector(":scope > [data-hedron-local='toggle']");
+    if (!btn) return;
+    this.#onToggle = () => {
+      this.#expanded = !this.#expanded;
+      this.#syncLocal();
+      const detail = { expanded: this.#expanded, status: this.getAttribute("status") };
+      if (!validateEventDetail(detail, ["expanded", "status"])) return;
+      this.dispatchEvent(
+        new CustomEvent(EVENT, { bubbles: true, composed: false, detail }),
+      );
+    };
+    btn.addEventListener("click", this.#onToggle, { signal: this.#signal });
+  }
+
+  #sync() {
+    const region = this.querySelector(":scope > [data-hedron-server-region='content']");
+    if (region) region.textContent = this.getAttribute("status") || "Ready";
+    this.#syncLocal();
+  }
+
+  #syncLocal() {
+    const panel = this.querySelector(":scope > [data-hedron-local='panel']");
+    const btn = this.querySelector(":scope > [data-hedron-local='toggle']");
+    if (panel) panel.hidden = !this.#expanded;
+    if (btn) btn.setAttribute("aria-expanded", this.#expanded ? "true" : "false");
+  }
+}
+
+if (!customElements.get(TAG)) {
+  customElements.define(TAG, HedronExample);
+}
+
+function enhance(root) {
+  const nodes = [];
+  if (root?.matches?.(TAG)) nodes.push(root);
+  root?.querySelectorAll?.(TAG)?.forEach((el) => nodes.push(el));
+  for (const el of nodes) {
+    if (el instanceof HedronExample && el.isConnected) {
+      el.connectedCallback();
+    }
+  }
+}
+
+document.addEventListener("htmx:afterSwap", (ev) => enhance(ev.target || document));
+document.addEventListener("htmx:load", (ev) => enhance(ev.target || document));