wings AGENTS.md

Writing apps with WINGS — agent guide

WINGS builds browser UI as Go compiled to WASM: each component is a custom element whose logic is Go, not JavaScript. This file is the always-on context; deeper, area-specific guidance lives in the wings-authoring Claude plugin (skills) and in README.md (section links below).

Mental model

• A module is a custom element = three files with the same basename: name.go (logic), name.html (template), name.css (styles).
• name.go runs wings.Register(tag, html, css, factory, ...observedAttrs) in init() and implements PranaMod: InitData() map[string]any (initial state) and Render(obj *wings.PranaObj) (runs after connect, obj available).
• State lives in obj.This (a reactive store: Set/Get/Append/DeleteAt). The DOM updates automatically from data changes — there is no virtual DOM and you never touch innerHTML.
• Components are shadow-DOM isolated. i18n is resolved at build time (gen_i18n rewrites templates); you author plain text.
• All component files carry //go:build js && wasm. The app entry point is func main() { wings.Main() } with blank imports of each module.

Non-negotiable gotchas (the #1 and #2 mistakes)

1. Binding NAMES in attributes must be lowercase — use snake_case. The browser lowercases attribute names, so a camelCase binding name silently becomes a no-op (wrong render, zero error). Applies to ?cond, *arr, **arr, &attr. {{textBinding}} in text content is exempt but use snake_case everywhere for consistency.

   <my-child ?is_logged show_extra="{{show_extra}}"></my-child>   <!-- CORRECT -->
   <my-child ?isLogged showExtra="{{showExtra}}"></my-child>      <!-- WRONG: no-op -->
   

   go run ./cmd/build <target> fails the build on any uppercase binding name, with file:line. Treat a lint failure here as "rename to snake_case".

2. Event handlers that need obj can't be built in InitData (obj isn't ready yet). Put wings.TriggerHandler(nil) as a placeholder in InitData, then set the real func(args ...any){...} in Render via obj.This.Set.