@cychien/ezdesign 0.0.0-stage → 0.9.1

package/skills/ezdesign/reference/stack.md

@@ -0,0 +1,123 @@
+# Define the project's stack and tools
+
+> Only for a turn whose prompt says 增強設計 (the design harness) is on for it, or a request that
+> asks for it by name. In any other turn, handle the request as if you had never read this file.
+
+## What this file is
+
+`.ezdesign/config.json` at the project root records the architecture the application is built on,
+the design system and component library it already uses, and where the tools used to work on it
+come from. Later steps read it instead of rediscovering any of it: the stack and the component
+library tell the components and making steps what code to write and in which style, and the tools
+tell every step how to look at the running page.
+
+The platform is web only, so the stack is a web stack.
+
+```json
+{
+  "platform": "web",
+  "stack": ["vite", "react", "typescript", "tailwind"],
+  "design_system": { "kind": "tailwind", "path": "tailwind.config.ts" },
+  "components": { "library": "shadcn", "path": "src/components/ui" },
+  "tools": {
+    "browser": {
+      "name": "playwright",
+      "via": "cli",
+      "invoke": "npx playwright",
+      "notes": "In the project's devDependencies; `npx playwright screenshot <url> out.png`."
+    }
+  }
+}
+```
+
+- `platform` is always `"web"`.
+- `stack` is a list of lower-case keywords, the names the ecosystem itself uses: `react`, `nextjs`,
+  `vite`, `astro`, `sveltekit`, `vue`, `typescript`, `tailwind`, `css-modules`, `static-html`.
+  Framework, language and styling approach at least.
+- `design_system` is where the project's tokens live: `kind` is the idiom (`tailwind`,
+  `css-variables`, `css-in-js`, or a component library's own theme such as `mui`) and `path` is the
+  file an agent reads. `null` when the project has no tokens anywhere, only literal values.
+- `components` is how the project writes components. `library` is the component library's name as
+  its ecosystem spells it (`shadcn`, `mui`, `chakra`, `mantine`, `antd`, `headlessui`, `vuetify`),
+  `custom` for the project's own components built on no library, or `none` when there is no
+  component layer yet. `path` is where the components live, or will. `notes` is optional: a second
+  library in use, a wrapper convention, anything the next step would otherwise trip over. The
+  components step adds `primitives` here once it has built the set.
+- `tools` is keyed by role. `browser` is the one this step fills; later steps add their own.
+  Each tool says what it is (`name`), what kind of thing it is (`via`: `"skill"`, `"mcp"` or
+  `"cli"`), and what an agent does to use it (`invoke`: the skill to load, the MCP server whose
+  tools to call, or the command to run). `notes` is optional and holds what an agent would
+  otherwise have to find out again: a flag, a prerequisite, a limit.
+- A tool that was looked for and not found is recorded as `null`, so later steps know not to look
+  again and can tell the user what to install.
+
+## Step 1: Load current state
+
+If there is no `PRODUCT.md`, run [product.md](product.md) first and come back: the stack of a
+new project is inferred from what the product is.
+
+Read `.ezdesign/config.json` if it exists. Take its values as the record of an earlier pass, to be
+checked against the project now, not as truth.
+
+## Step 2: Define the architecture
+
+### The project already has code
+
+Read what it is built on: `package.json` dependencies and scripts, the framework's config file,
+the lockfile, how styles are written, the language. Record the keywords.
+
+Then read what it already designs with, because every component added later has to be written the
+way these ones are:
+
+- **The design system.** A Tailwind config or a CSS `@theme` block; `:root` custom properties; a
+  CSS-in-JS theme; a component library's theme object. Record the one the project treats as the
+  source, and `null` when the values are only literal.
+- **The component library.** `components.json` at the root, or `@radix-ui/*` with
+  `class-variance-authority` and a `components/ui` directory, is `shadcn`; a library in
+  `package.json` (`@mui/material`, `@chakra-ui/react`, `@mantine/core`, `antd`,
+  `@headlessui/react`, `vuetify`) is that library; a components directory built on none of them is
+  `custom`. When two are in use, record the one most of the components are built on and name the
+  other in `notes`. Never assume one from the framework: a React project is not a shadcn project
+  until the files say so.
+
+If the config already holds a stack, compare it with what you found. A keyword the project no
+longer uses, or a framework it has moved off, makes the record legacy: replace it with the current
+stack and say in one line what changed.
+
+### The project is new
+
+Recommend a stack from `PRODUCT.md`. A simple site with no data, accounts or growth to plan for is
+served by the simplest architecture that renders it; a product with users, state and screens that
+will multiply is served by a component framework. Match the weight of the stack to the product,
+not to fashion.
+
+When more than one stack fits, or `PRODUCT.md` cannot settle it, ask the user. They may not be
+technical, so do the narrowing for them: at most three candidates, each in one line that says what
+choosing it means for *their product* - how fast it ships, what it costs to host, what it can grow
+into, what it locks them out of - in the user's own language, no framework jargon without a
+plain-words gloss. Lead with the one you recommend and mark it as recommended. Use the structured
+question tool when available; otherwise ask in your reply and wait.
+
+The design system and the component library follow from the stack. A new React project uses
+`shadcn` with Tailwind as its design system. Any other new project records `custom`, with its
+tokens in the stack's own idiom, unless the user asks for a library by name.
+
+Record the decision. Creating the project itself is the first making request, not this step.
+
+## Step 3: Define the tool sources
+
+**Browser tool.** Every later step looks at the rendered page, so find the tool this agent can
+actually use to open a URL, take a screenshot and read computed styles. Look, in order, at: a skill
+the agent has that drives a browser; an MCP server that does; a CLI the project or the machine has
+installed (Playwright, Puppeteer, a headless Chrome). Prefer the one that needs no install. Record
+it under `tools.browser`, with `invoke` precise enough that an agent that has never seen this
+project can use it without a search, and put anything it would trip over in `notes`.
+
+When nothing is found, record `"browser": null` and tell the user which tool to install; the
+making and reviewing steps then work from source alone and say so.
+
+## Step 4: Wrap up or resume
+
+Write `.ezdesign/config.json`, creating the directory if needed. Say something to the user only
+when they have to act on it - no browser tool was found, and here is how to install one. The rest
+of this step is the harness's own business. Then end, or resume the request that invoked this.

package/skills/ezdesign/reference/start.md

@@ -0,0 +1,78 @@
+# Open a review
+
+ezdesign turns a locally running dev server into an annotatable review surface. Start the session
+with an ACP agent, then let that agent own the feedback loop. It receives each annotation batch,
+edits the source, and streams its work, questions, permission prompts, and replies into the review
+shell while the app's HMR updates the page in place.
+
+You do not need ezdesign installed globally. Invoke it as `npx -y @cychien/ezdesign@latest ...`.
+
+## When to use
+
+- You just generated or significantly changed a page or component and the user should review it visually
+- The user wants to give feedback by pointing at things instead of describing them in chat
+- You are iterating on visual, copy, or layout details where prose descriptions are lossy
+
+## Agent profile
+
+Use the ACP profile matching the current coding-agent environment unless the user explicitly names
+another ACP agent or command:
+
+- Claude Code: `claude`
+- Codex: `codex`
+- Gemini CLI: `gemini`
+
+Every skill invocation uses ACP mode. Never omit `--agent`, never run `ezdesign poll`, and never fall
+back to Poll mode after an ACP failure. If the environment does not identify a supported profile and
+the user did not provide an ACP command, ask them which ACP agent to use.
+
+## Workflow
+
+1. Make sure the dev server is running. Never start a second instance when one is already up. If
+   the user only wants to explore designs on a canvas, there may be no dev server: run the command
+   below without the url and the review opens on the project's canvases.
+2. From the project root, run:
+
+   ```sh
+   npx -y @cychien/ezdesign@latest <url> --agent <profile>
+   ```
+
+   Use the full URL of the page to review, for example:
+
+   ```sh
+   npx -y @cychien/ezdesign@latest http://localhost:5173/pricing --agent codex
+   ```
+
+   The working directory matters because the session and spawned agent are scoped to that project.
+   If the CLI says the user previously ended the session, do not pass `--reopen` unless the user
+   explicitly asked to review again.
+3. Once the CLI reports the session and agent, tell the user the review shell is ready. Do not start
+   a parallel feedback loop or shadow the ACP agent's edits. The daemon delivers queued and future
+   batches automatically, one turn at a time. The shell owns the turn: the user can stop one that is
+   heading the wrong way (the Stop button, or Cmd/Ctrl+.), `/new` in the note box clears the agent's
+   context and carries the review on in a fresh session, and a batch sent mid-turn queues rather
+   than interrupting - so do not tell the user to wait for a turn to finish before annotating.
+4. The user ends the review from the shell. Do not end or stop a live session unless they ask.
+
+## Failures and switching agents
+
+- If the ACP command is missing, unauthenticated, or exits, report that error and help fix that ACP
+  setup. Do not substitute Poll mode.
+- A live session can own only one ACP agent. If the CLI refuses a different agent, do not stop the
+  daemon automatically because it may hold other sessions. Ask the user whether to end the current
+  session or stop the daemon before switching.
+- Do not retry a failing launch indefinitely. After one retry for a transient failure, report the
+  blocker and preserve the session state.
+
+## Source anchors
+
+Projects using Vite get exact `file:line` anchors by adding the bundled plugin:
+
+```ts
+// vite.config.ts
+import { ezdesignSource } from '@cychien/ezdesign/vite'
+// plugins: [ezdesignSource(), ...]
+```
+
+Suggest this dev-only plugin when feedback repeatedly arrives without exact source locations. It has
+no production-build impact.

package/skills/ezdesign/scripts/page.d.mts

@@ -0,0 +1,61 @@
+export interface Png {
+  width: number
+  height: number
+  channels: 3 | 4
+  pixels: Buffer
+}
+
+export type Diff =
+  | { same: true }
+  | {
+      same: false
+      changed: number
+      box: { left: number; top: number; right: number; bottom: number }
+    }
+  | { same: false; size: { before: string; after: string } }
+
+export type Comparison = { name: string } & (Diff | { same: false; missing: 'before' | 'after' })
+
+export const DESKTOP: { width: number; height: number }
+export const MOBILE: { width: number; height: number }
+export function shotName(path: string): string
+export function decodePng(buffer: Buffer): Png
+export function diffPngs(before: Buffer, after: Buffer): Diff
+export function compare(beforeDir: string, afterDir: string): Comparison[]
+export function describe(result: Comparison): string
+export function findChrome(env?: Record<string, string | undefined>, platform?: string): string
+export type ShotState = 'hover' | 'focus' | 'active'
+export const STATES: ShotState[]
+export function shotFiles(
+  file: string,
+  sizes: { width: number; height: number }[],
+  page: boolean,
+  states?: { state: ShotState; target: string }[],
+): {
+  size: { width: number; height: number }
+  file: string
+  kind: 'piece' | 'page' | ShotState
+  target?: string
+}[]
+export function statesFrom(
+  named: Record<string, string | true>,
+  around: string | null,
+): { state: ShotState; target: string }[]
+export function parseViewport(raw: string | undefined): { width: number; height: number }
+export function flags(args: string[]): { named: Record<string, string | true>; rest: string[] }
+
+export interface StorageEntry {
+  name: string
+  value: string
+}
+export interface SignIn {
+  cookies: { name: string; value: string; domain: string; path: string }[]
+  storage: {
+    localStorage: StorageEntry[]
+    sessionStorage: StorageEntry[]
+    indexedDB: unknown[]
+  } | null
+}
+export function sameOrigin(a: string, b: string): boolean
+export function signInFor(origin: string, state: unknown): SignIn | null
+export function landedElsewhere(requested: string, landed: string): boolean