Start CrychicUI: module, license, agents guide, readme, notices

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-17 01:19:47 -04:00
commit 03471f9dff
@@ -0,0 +1,12 @@
+.DS_Store
+/.claude/
+/.wrangler/
+PRD.md
+TASKS.md
+docs/prd/
+docs/acceptance.md
+/gallery.exe
+/web/dist/
+/web/node_modules/
+/web/test-results/
+/web/playwright-report/
@@ -0,0 +1,97 @@
+# AGENTS.md
+
+CrychicUI: 1500 components for MyGo native UI, in MyGo's own look, with motion and sound cues. Go module
+`git.zacharyzhang.com/ZacharyZhang-NY/CrychicUI`.
+Progress truth: `TASKS.md`. Requirements: `PRD.md` and `docs/prd/catalog-*.md` (both local, not committed).
+
+## Stack
+
+| Item | Value |
+| --- | --- |
+| Go | 1.27.1 |
+| MyGo | `github.com/egoist/mygo v0.5.5`, pinned; CLI pinned as `go tool mygo` |
+| Sound | `github.com/egoist/mygo/audio`, cues synthesized in `sound` |
+| Icons | Lucide (ISC), `icon/svg` |
+| Web | `cmd/gallery` built for `js/wasm`; MyGo's browser backend draws it with WebGL 2 |
+| Hosting | Cloudflare Workers static assets from `web/dist`; code on Gitea `git.zacharyzhang.com` |
+
+Read MyGo source before using an API: `go list -m -f '{{.Dir}}' github.com/egoist/mygo` (`ui/*.go`, `ui/doc.go`,
+`docs/ui/*.md`, `audio/*.go`). Never guess.
+
+## Layout
+
+```text
+sound/              synthesized cues, Play, mute, Recent
+icon/               Lucide SVGs, parsed on first use
+kit/                helpers shared by three or more components
+<category>/         one component per file, package = folder name
+gallery/            registry, demos (demos_<category>*.go), app view, tests
+cmd/gallery/        one main for desktop and browser; hook_js.go for tests
+web/                shell, build.sh, deploy.sh, wrangler.jsonc, _headers, Playwright tests
+internal/archtest/  import and file rules
+```
+
+## Tiers
+
+Imports point down only. Same-tier imports are forbidden. `internal/archtest` enforces it.
+
+0 sound, icon · 1 kit · 2 layout, typography, button, display · 3 input, choice, feedback, motion, fx ·
+4 form, datetime, color, navigation, overlay, data, chart, media ·
+5 chat, agent, code, files, shop, finance, dashboard, schedule, project, mail, social, account, devtools, game, learn,
+health, home, marketing, content, desktop, geo · 6 gallery · 7 cmd/gallery
+
+## Look
+
+- Colors from `c.Theme()` only, tints by `Mix` and `Alpha`. No hex in components.
+- Sizes from `t.Space(n)`, `t.Rem(n)`, `t.Radius`. Pills use radius 999. Hairlines are 1 DIP of `Border`.
+- One soft shadow at most on cards; larger only on popups. No glow.
+- Lucide icons in the text color, 16 DIP in controls.
+- Focus ring and disabled dimming are MyGo's. Never redraw them.
+
+## Components
+
+- `func Name(c *ui.Context, required...) ui.Element`; optional knobs in a final `NameOptions` (never variadic). Zero
+  options give the default look. Containers take content as a final `func()`. Several actions: a `NameResult` of
+  named `ui.Element` fields.
+- Value-bound components take `*T` and call `SetChanged` on the returned element when input changes it.
+- Stateful components get their key from the caller (`c.Key`); private state lives in `ui.Local`.
+- Every component moves: pose, color animation, transition, content transition, keyframes, loop or animated drawing.
+  Reduce Motion is MyGo's job.
+- Every interactive component plays one cue on its action through `kit` or `sound.Play`, from a handled action:
+  views may build several times for one event.
+- Copy shown by a component comes from the caller; built-in defaults are English and overridable.
+- Fail fast: panic on programmer errors. Never swallow an error.
+- Composites log state changes with `kit.Log`. Never log typed text or secrets: log counts.
+- No element or parts stored across builds; no goroutine touches elements. `go tool mygo vet ./...` passes.
+- Files under 500 lines. Comments one line, ten words at most, only when needed. No dead code, no versioned APIs.
+
+## Gallery entry
+
+Each component adds one `Entry` in `gallery/demos_<category>*.go`: ID, Name, Category, Summary, Demo. The demo reports
+every event through `log`. The code panel shows the demo function's own source.
+
+## Tests
+
+- `go vet ./... && go tool mygo vet ./... && go test ./...` and `GOOS=js GOARCH=wasm go vet ./...` before done.
+- Behavior tests drive `ui.NewTester` and assert values; interactive tests assert the cue in `sound.Recent()`.
+  Advance the tester's clock; never sleep.
+- Web: `npm install && npm test` in `web/` builds `web/dist` and runs Playwright on a local server;
+  `BASE_URL=<url> npx playwright test` checks a deployed site. Tests read `window.__crychic`.
+
+## Deploy
+
+- `npm run deploy` in `web/` (clean tree only): live page beside new files first, then the new page tested on its
+  preview URL, promoted, and tested live at https://crychicui.zhangyanghaha0407.workers.dev.
+- Rollback: `npx wrangler rollback <version-id>` in `web/`.
+
+## Review
+
+Each TASKS.md item is reviewed in a Herdr pane split to the right by
+`codex --yolo -m gpt-6.1-sol -c model_reasoning_effort=xhigh -c service_tier=fast`. At most three rounds. The reviewer
+reports defects against PRD and this file, ends with `VERDICT: PASS` or `VERDICT: FAIL`, and does not reject work for
+missing enhancements.
+
+## Secrets
+
+The Gitea token lives only in the environment (`GITEA_TOKEN`). Never write it to a file, a remote URL, a commit or a
+log. Pushes pass it as an HTTP header.
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrychicUI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,33 @@
+# CrychicUI
+
+MyGo 原生 UI 的 Go 组件库。沿用 MyGo 自己的外观：锌灰底色，跟随系统的强调色，6 DIP 圆角，4 DIP 间距单位，系统字体。每个组件都会动，每个可交互组件都有合成音效。
+
+界面由 MyGo 在 GPU 上自绘，不用 HTML、JavaScript 或 WebView。
+
+## 安装
+
+```sh
+go get git.zacharyzhang.com/ZacharyZhang-NY/CrychicUI
+```
+
+要求 Go 1.27.1 与 MyGo v0.5.5。
+
+## 音效
+
+可交互组件在动作时播放一个音效，默认开启。
+
+```go
+sound.SetEnabled(false) // 全部静音
+```
+
+## Gallery
+
+```sh
+go run ./cmd/gallery
+```
+
+同一个程序编译成 WebAssembly，就是网站：https://crychicui.zhangyanghaha0407.workers.dev
+
+## 许可
+
+MIT。第三方声明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
@@ -0,0 +1,13 @@
+# Third-party notices
+
+## Go module dependencies
+
+Linked, not copied. Licenses ship with each module.
+
+| Module | Version | License |
+| --- | --- | --- |
+| github.com/egoist/mygo | v0.5.5 | MIT |
+| github.com/ebitengine/purego | v0.11.1 | Apache-2.0 |
+| github.com/go-text/typesetting | v0.3.5 | BSD-3-Clause OR Unlicense |
+| golang.org/x/image | v0.46.0 | BSD-3-Clause |
+| golang.org/x/text | v0.43.0 | BSD-3-Clause |
@@ -0,0 +1,10 @@
+module git.zacharyzhang.com/ZacharyZhang-NY/CrychicUI
+
+go 1.27.1
+
+require (
+	github.com/egoist/mygo v0.5.5 // indirect
+	golang.org/x/text v0.43.0 // indirect
+)
+
+tool github.com/egoist/mygo/cmd/mygo
@@ -0,0 +1,4 @@
+github.com/egoist/mygo v0.5.5 h1:3pvlEwumsck/L99cbDpay/Eqcf51B7zhKNXekiodLOw=
+github.com/egoist/mygo v0.5.5/go.mod h1:daHGetyAlBkHhIZOOIcAI7C82yLUY7HgeT2+Z6w2VPU=
+golang.org/x/text v0.43.0 h1:1QivrlhwAsnMOcqgOdl9my7s9OyZl8O5/UGUTJVXoWc=
+golang.org/x/text v0.43.0/go.mod h1:hbSIYA/amXcRXTFSZqh8tWHEoqRvvbKPJ2uz/KU+a+s=