Release v4.0.0

.github/CODEOWNERS

@@ -0,0 +1,11 @@
+# Default owner fallback.
+* @monstercameron
+
+# Release and CI automation are protected surfaces.
+/.github/workflows/ @monstercameron
+
+# Transport/runtime library changes require explicit owner review.
+/third_party/GoGRPCBridge/ @monstercameron
+
+# Release-readiness roadmap and integration docs.
+/docs/GOGRPCBRIDGE_*.md @monstercameron

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,44 @@
+name: Bug report
+description: A concrete, reproducible defect in the framework, runtime, or gwc tooling.
+labels: ["bug", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. A **minimal reproduction** is the single most
+        useful thing you can include — the smallest `main.go` plus the `gwc`
+        command that triggers the problem. First-response target: 5 business
+        days (see CONTRIBUTING.md → Triage SLA).
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What did you observe, and what did you expect instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: The smallest code + the exact `gwc`/`go` command that reproduces it.
+      render: shell
+    validations:
+      required: true
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      description: "Output of `go version` and the GoWebComponents version/commit."
+    validations:
+      required: true
+  - type: dropdown
+    id: lane
+    attributes:
+      label: Where does it occur?
+      options:
+        - Browser (js/wasm)
+        - Server / SSR (native)
+        - gwc tooling
+        - Both / unsure
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,13 @@
+# Issues are for concrete, reproducible defects. Questions, ideas, and show-and-tell go to
+# Discussions; security reports follow the disclosure policy.
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & Help (Q&A)
+    url: https://github.com/monstercameron/GoWebComponents/discussions/categories/q-a
+    about: Ask how to do something, or "is this a bug?" before filing an issue.
+  - name: Ideas & Feature Proposals
+    url: https://github.com/monstercameron/GoWebComponents/discussions/categories/ideas
+    about: Propose a feature or direction. Accepted ideas are linked from ROADMAP.md.
+  - name: Security Disclosure
+    url: https://github.com/monstercameron/GoWebComponents/security/policy
+    about: Report a vulnerability privately. Do NOT open a public issue.

.github/workflows/agent-bridge-headless.yml

@@ -0,0 +1,87 @@
+name: Agent Bridge Headless
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/agent-bridge-headless.yml"
+      - "AGENTS.md"
+      - "agentbridge/**"
+      - "docs/REFERENCE_MANUAL/**"
+      - "examples/public-examples-site/assets/docs/**"
+      - "examples/server/ai-chat-wizard/**"
+      - "internal/runtime/**"
+      - "security/**"
+      - "test/playwrightgo/**"
+      - "tools/agenthub/**"
+      - "tools/gwc/**"
+      - "tools/livereload/**"
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - ".github/workflows/agent-bridge-headless.yml"
+      - "AGENTS.md"
+      - "agentbridge/**"
+      - "docs/REFERENCE_MANUAL/**"
+      - "examples/public-examples-site/assets/docs/**"
+      - "examples/server/ai-chat-wizard/**"
+      - "internal/runtime/**"
+      - "security/**"
+      - "test/playwrightgo/**"
+      - "tools/agenthub/**"
+      - "tools/gwc/**"
+      - "tools/livereload/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  PLAYWRIGHT_GO_VERSION: v0.5700.1
+
+jobs:
+  bridge-headless:
+    name: Bridge Native + Headless Dogfood
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: "1.26.x"
+
+      - name: Install Playwright Chromium
+        run: go run github.com/playwright-community/playwright-go/cmd/playwright@${{ env.PLAYWRIGHT_GO_VERSION }} install --with-deps chromium
+
+      - name: Run native agent bridge lane
+        run: go run ./tools/gwc test -lane agent -json
+
+      - name: Prebuild agent dogfood client
+        run: |
+          mkdir -p examples/server/ai-chat-wizard/bin/client/app
+          GOOS=js GOARCH=wasm go build -tags gwcagent -o examples/server/ai-chat-wizard/bin/client/app/chat.wasm ./examples/server/ai-chat-wizard/client
+
+      - name: Prebuild agent dogfood server
+        run: |
+          mkdir -p bin/ci
+          go build -o bin/ci/example100-agent-dogfood-server ./examples/server/ai-chat-wizard/cmd/server
+
+      - name: Run headless agent bridge dogfood lane
+        env:
+          GWC_AGENT_DOGFOOD_REUSE_CLIENT_WASM: "1"
+          GWC_AGENT_DOGFOOD_SERVER_BINARY: bin/ci/example100-agent-dogfood-server
+          GWC_AGENT_DOGFOOD_TRACE: "1"
+        run: |
+          while sleep 20; do
+            echo "agent-browser dogfood still running..."
+          done &
+          keepalive_pid="$!"
+          trap 'kill "$keepalive_pid" 2>/dev/null || true' EXIT
+          go test -tags playwrightgo -run 'TestExample100AgentBridgeDogfood|TestAgentBridgeDogfood|TestAgentBridgeHeadless' -count=1 -timeout=5m -v ./test/playwrightgo/examples

.github/workflows/api-baseline.yml

@@ -0,0 +1,39 @@
+name: API Baseline
+
+# F3 merge gate: the public-API baseline tests run on every PR (and push to main), so an
+# accidental breaking change to an exported surface fails BEFORE merge — not only at release
+# tag time. This makes the major/minor boundary (VERSIONING.md) mechanically enforced: a removed
+# or changed baseline line fails the gate; an intentional change regenerates the baseline
+# (UPDATE_API_BASELINE=1 go test ./<pkg>/) as a reviewed commit.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  api-baseline:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: "1.26.x"
+
+      - name: Public-API baseline gate
+        # No continue-on-error: any exported-surface drift fails the PR. Covers every package
+        # whose public API is pinned with an api_baseline.txt.
+        run: |
+          go test -count=1 \
+            ./serverfn/ ./query/ ./localfirst/ ./agentui/ ./validate/ \
+            ./anim/ ./timetravel/ ./workbench/ ./wholestack/ \
+            -run 'APIBaseline|ApiBaseline|API_BASELINE'

.github/workflows/bench-drift.yml

@@ -0,0 +1,37 @@
+name: Bench Drift
+
+# D3 merge gate: a benchmark that regresses beyond the tolerance fails the build, so a
+# performance regression cannot land silently. The run compares the fresh native benchmark
+# numbers against the committed baseline (docs/benchmarks/latest.json) and exits non-zero on any
+# out-of-tolerance regression via `gwc bench -fail-on-regression`. Benchmarks are pinned to a
+# single package run (-parallel 1) for the lowest-noise comparison.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  bench-drift:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: "1.26.x"
+
+      - name: Build gwc
+        run: go build -o gwc ./tools/gwc
+
+      - name: Benchmark drift gate (native lane)
+        # Compares against the committed baseline and fails on any out-of-tolerance regression.
+        run: ./gwc bench -lane native -parallel 1 -fail-on-regression

.github/workflows/browser-compatibility.yml

@@ -0,0 +1,30 @@
+name: Browser Compatibility
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  compatibility-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: "1.26.x"
+
+      - name: Run Browser Compatibility Smoke (Playwright-Go)
+        run: |
+          go test -tags playwrightgo ./test/playwrightgo/examples -run TestBrowserCompat -v

.github/workflows/build-times.yml

@@ -0,0 +1,53 @@
+name: Build Times
+
+# A2/C2 platform-honest gate: publishes the cold-vs-warm build-time pair and fails the build if
+# the Go build cache stops delivering a speedup (warm rebuild slower than -max-warm-ratio of the
+# cold build). CI starts from a cold cache, so the cold/warm differential is real and meaningful.
+# The gate targets the WASM build of a representative app (the workload A2/C2 actually care about —
+# wasm compile time, not the native CLI), recomputes timings fresh each run, and gates on the
+# machine-independent warm/cold ratio (absolute ms vary by hardware). The committed
+# docs/benchmarks/build-times.json is a portable reference snapshot; the gate does not depend on
+# it, so it cannot silently drift the build green/red — the fresh artifact is uploaded each run.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-times:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: "1.26.x"
+
+      - name: Build gwc
+        run: go build -o gwc ./tools/gwc
+
+      - name: Cold/warm WASM build-time gate
+        # Cold wasm build (CI cache is empty) then an immediate warm rebuild of the counter app;
+        # fails if the warm rebuild is not at least 40% faster than the cold one
+        # (-max-warm-ratio 0.6), proving the build cache delivers for the wasm target. Writes the
+        # fresh report to docs/benchmarks/build-times.json (uploaded below).
+        run: |
+          ./gwc warm -once -target wasm -pattern ./examples/public/counter \
+            -baseline docs/benchmarks/build-times.json \
+            -max-warm-ratio 0.6 -fail-on-regression -json
+
+      - name: Upload build-time report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-times
+          path: docs/benchmarks/build-times.json

.github/workflows/catalog-smoke.yml

@@ -0,0 +1,72 @@
+name: Catalog Smoke
+
+# FA3: prove every `gwc add` catalog component compiles AFTER being copied into a fresh module
+# (not just in-repo). For each component we scaffold a throwaway module that requires the local
+# GoWebComponents via a replace directive, `gwc add` the component, write a tiny consumer, and
+# `go build` it. A template that does not compile standalone fails the gate.
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  catalog-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: "1.26.x"
+
+      - name: Build gwc
+        run: go build -o gwc ./tools/gwc
+
+      - name: gwc add → go build each catalog component
+        shell: bash
+        run: |
+          repo="$(pwd)"
+          for name in alert breadcrumb disclosure switch tabs; do
+            work="$(mktemp -d)"
+            ( cd "$work"
+              go mod init example.com/catalog-smoke
+              echo "require github.com/monstercameron/GoWebComponents v0.0.0" >> go.mod
+              echo "replace github.com/monstercameron/GoWebComponents => $repo" >> go.mod
+              mkdir -p uikit
+              "$repo/gwc" add "$name" -dir ./uikit -pkg uikit
+              # Tiny consumer so the package is actually compiled, not just present.
+              printf 'package main\nimport _ "example.com/catalog-smoke/uikit"\nfunc main() {}\n' > main.go
+              go mod tidy
+              echo "Building catalog component: $name"
+              go build ./...
+            )
+            rm -rf "$work"
+          done
+
+      - name: gwc add component/route generators → go build
+        # A3 10-rung "CI-verified": the composable sub-generators must also produce compiling code
+        # in a fresh module, not just parse. Scaffold a component and a route into a throwaway
+        # module and build them.
+        shell: bash
+        run: |
+          repo="$(pwd)"
+          work="$(mktemp -d)"
+          ( cd "$work"
+            go mod init example.com/generator-smoke
+            echo "require github.com/monstercameron/GoWebComponents v0.0.0" >> go.mod
+            echo "replace github.com/monstercameron/GoWebComponents => $repo" >> go.mod
+            "$repo/gwc" add component MyWidget -dir ./ui -pkg ui
+            "$repo/gwc" add route Home -path /home -dir ./ui -pkg ui
+            printf 'package main\nimport _ "example.com/generator-smoke/ui"\nfunc main() {}\n' > main.go
+            go mod tidy
+            echo "Building generated component + route"
+            go build ./...
+          )
+          rm -rf "$work"