(defcomp
  ()
  (~docs/page
    :title "How defisland Works"
    (p
      (code "defisland")
      " creates a reactive component. Same calling convention as "
      (code "defcomp")
      " — keyword args, rest children — but with a reactive boundary. Inside an island, "
      (code "deref")
      " subscribes DOM nodes to signals.")
    (~docs/code
      :src (highlight
        ";; Definition — same syntax as defcomp\n(defisland ~reactive-islands/demo/counter (&key initial)\n  (let ((count (signal (or initial 0))))\n    (div\n      (span (deref count))                          ;; reactive text node\n      (button :on-click (fn (e) (swap! count inc))  ;; event handler\n        \"+\"))))\n\n;; Usage — same as any component\n(~reactive-islands/demo/counter :initial 42)\n\n;; Server-side rendering:\n;; <div data-sx-island=\"counter\" data-sx-state='{\"initial\":42}'>\n;;   <span>42</span><button>+</button>\n;; </div>\n;;\n;; Client hydrates: signals + effects + event handlers attach"
        "lisp"))
    (p
      "Each "
      (code "deref")
      " call registers the enclosing DOM node as a subscriber. Signal changes update "
      (em "only")
      " the subscribed nodes — no virtual DOM, no diffing, no component re-renders.")))
