;; ---------------------------------------------------------------------------
;; Fragment Protocol
;; ---------------------------------------------------------------------------

(defcomp ()
  (~docs/page :title "Fragment Protocol"

    (~docs/section :title "Context" :id "context"
      (p "Fragment endpoints return raw sexp source (e.g., " (code "(~blog-nav-wrapper :items ...)") "). The consuming service embeds this in its page sexp, which the client evaluates. But service-specific components like " (code "~blog-nav-wrapper") " are only in that service's component env — not in the consumer's. So the consumer's " (code "client_components_tag()") " never sends them to the client, causing \"Unknown component\" errors.")
      (p "The fix: transfer component definitions alongside fragments. Services tell the provider what they already have; the provider sends only what's missing."))

    (~docs/section :title "What exists" :id "exists"
      (div (~tw :tokens "rounded border border-green-200 bg-green-50 p-4")
        (ul (~tw :tokens "list-disc pl-5 text-stone-700 space-y-1")
          (li "Fragment GET infrastructure works (" (code "shared/infrastructure/fragments.py") ")")
          (li (code "X-Fragment-Request") " header protocol for internal service calls")
          (li "Content type negotiation for text/html and text/sx responses")
          (li "Fragment caching and composition in page rendering"))))

    (~docs/section :title "What remains" :id "remains"
      (div (~tw :tokens "rounded border border-amber-200 bg-amber-50 p-4")
        (ul (~tw :tokens "list-disc pl-5 text-stone-700 space-y-1")
          (li (strong "POST sexp protocol: ") "Switch from GET to POST with structured sexp body containing " (code ":components") " list of what consumer already has")
          (li (strong "Structured response: ") (code "(fragment-response :defs (...) :content (...))") " — provider sends only missing component defs")
          (li (strong (code "fragment_response()") " builder: ") "New function in helpers.py that diffs provider's component env against consumer's list")
          (li (strong "Register received defs: ") "Consumer parses " (code ":defs") " from response and registers into its " (code "_COMPONENT_ENV"))
          (li (strong "Shared blueprint factory: ") (code "create_fragment_blueprint(handlers)") " to deduplicate the identical fragment endpoint pattern across 8 services"))))

    (~docs/section :title "Files to modify" :id "files"
      (div (~tw :tokens "overflow-x-auto rounded border border-stone-200")
        (table (~tw :tokens "w-full text-left text-sm")
          (thead (tr (~tw :tokens "border-b border-stone-200 bg-stone-100")
            (th (~tw :tokens "px-3 py-2 font-medium text-stone-600") "File")
            (th (~tw :tokens "px-3 py-2 font-medium text-stone-600") "Change")))
          (tbody
            (tr (~tw :tokens "border-b border-stone-100")
              (td (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700") "shared/infrastructure/fragments.py")
              (td (~tw :tokens "px-3 py-2 text-stone-700") "POST sexp body, parse response, register defs"))
            (tr (~tw :tokens "border-b border-stone-100")
              (td (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700") "shared/sx/helpers.py")
              (td (~tw :tokens "px-3 py-2 text-stone-700") "fragment_response() builder"))
            (tr (~tw :tokens "border-b border-stone-100")
              (td (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700") "shared/infrastructure/fragment_endpoint.py")
              (td (~tw :tokens "px-3 py-2 text-stone-700") "NEW — shared blueprint factory"))
            (tr (~tw :tokens "border-b border-stone-100")
              (td (~tw :tokens "px-3 py-2 font-mono text-sm text-violet-700") "*/bp/fragments/routes.py")
              (td (~tw :tokens "px-3 py-2 text-stone-700") "All 8 services: use create_fragment_blueprint"))))))))

;; ---------------------------------------------------------------------------
;; Glue Decoupling
;; ---------------------------------------------------------------------------
