feat(components): <zl-gate> atom, null-safe invisible atoms, mock gate verification

[peintnermax]

Implements the frontend side of ADR 016 — the in-flow captcha gate contract.

<zl-gate> atom

New invisible Lit component that handles gate proof-of-work. Reads gate config from step attributes, dispatches on kind + provider, solves the challenge, and emits zl-gate-result. The orchestrator collects proofs into a gateProofs map and includes them as gate_proofs in the submit body.

Supported providers: Altcha (built-in PoW), Turnstile, hCaptcha, reCAPTCHA. Third-party widgets mount in light DOM to avoid shadow-DOM iframe issues.

Null-safe invisible atoms

Both invisible auto-acting atoms (<zl-gate>, <zl-passkey>) now follow the same pattern:

• Always present in templates — no {% if %} guards needed
• Use firstUpdated() instead of connectedCallback() (Lit reflects attributes after connectedCallback, so config/options would be null)
• Silently no-op when their data is null; activate when data becomes available

This removes the {% if challenge and challenge.method == "passkey" %} boilerplate from all three Liquid templates. Custom branding authors no longer need to know about invisible atoms.

mandatory-gates → required-atoms rename

The patcher injects missing fields, gates, and submit buttons — not just gates. Renamed to reflect its actual scope:

• File: mandatory-gates.ts → required-atoms.ts
• Tag: {% mandatory_gates %} → {% required_atoms %}
• Exports: patchRequiredAtoms, REQUIRED_ATOMS_MARKER, requiredAtomsMarkerComment

Updated across all templates, specs, orchestrator imports, barrel exports, ADR 016, and 5 design docs.

Mock server gate verification

• packages/api-mock/src/altcha.ts — generateAltchaChallenge() + verifyAltchaProof() using crypto.subtle
• packages/api-mock/src/handlers.ts — tracks issued challenges per gate name, verifies proofs on submit (opt-in via verifyGates: true), logs ✅/❌ results
• packages/api-mock/src/fixtures/login.ts — identifier step includes an Altcha gate (bot_check)
• Standalone server (server.ts) enables verification; unit tests disable it (default)

ADR 016 updates

• Status: Proposed → Accepted
• <zl-captcha> → <zl-gate> (generic name for future gate kinds)
• gate_proofs values: string → object ({ number, salt } for Altcha, { token } for vendors)
• mandatory-gates → required-atoms

Changed files

Package	Files
components/atoms	zl-gate.ts (new), zl-passkey.ts (null-safe + firstUpdated)
components/orchestrator	required-atoms.ts (renamed), required-atoms.spec.ts, liquid.ts, liquid.spec.ts, zitadel-login.ts, zitadel-login.spec.ts, index.ts
components/templates	auth-form.liquid.ts, passkey-upsell.liquid.ts, signed-in.liquid.ts
components	src/index.ts, src/manifests.ts, src/manifests.spec.ts
api-mock	altcha.ts (new), handlers.ts, server.ts, fixtures/login.ts
docs	adrs/016-captcha-gate-and-bot-signals.md, design/branding/*.md (5 files)

Test results

• 136 tests pass (116 components + 20 api-mock)
• Build clean

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nextgen	Ready	Preview, Comment	May 27, 2026 1:56pm

[fforootd]

replaced by #562