# Contributing to Posy

Thanks for helping. Posy is small on purpose: a beautiful page, a calm editor, agents that can edit it.
Before adding a feature, ask whether it makes the page more beautiful or the editor simpler.
Please follow the [Code of Conduct](CODE_OF_CONDUCT.md). To report a security problem, see [SECURITY.md](SECURITY.md) and do not open a public issue.

## Setup

```bash
npm install
npm run dev          # http://localhost:3000 (sign up; the first account owns the instance)
```

## Before you open a PR

```bash
npm run check        # TypeScript + example pages validate
npm test             # unit tests (Vitest)
npm run e2e          # sign-up to publish, API keys, MCP (Playwright; builds and starts its own server)
npm run build        # production build
```

The end-to-end tests use a throwaway database in `.scratch/e2e-data`, never your real data. Stop `npm run dev` first (one Next server per folder).

## Where things live

| Path | What |
|---|---|
| `src/lib/schema.ts` | The page format (Zod). Run `npm run schema` after changing it. |
| `src/lib/themes.ts` | Theme tokens. Every theme defines the same six pastel tints. |
| `src/lib/platforms.ts` | Social platforms and their icons (Simple Icons). |
| `src/lib/detect.ts` | Turns a pasted link into the right tile. |
| `src/components/page/` | The public page. Server components plus small client islands. |
| `src/components/studio/` | The editor (Zustand store, dnd-kit, shadcn/ui). |
| `src/app/api/` | Auth, REST (`v1`), hosted MCP (`mcp`), uploads, tracking. |
| `src/edition/` | What an instance allows (self-hosted vs hosted platform). |
| `src/db/` | Drizzle schema; migrations in `drizzle/`. |

## Adding a platform or a tile type

- **Platform:** add it to `PLATFORMS` with its icon, hosts and URL pattern, then add a case to `tests/unit/detect.test.ts`.
- **Tile type:** add a schema entry, a view in `tiles.tsx`, fields in `TileControls.tsx`, then run `npm run schema`.

## Adding a look

A look (the `style` of a page) is a set of components that draw the same tiles their own way. Offer six at most; `minimal` stays only as the hidden fallback. Touch these files, in this order:

1. `src/lib/schema.ts`: add the id to `STYLES` (and to `BASE_FONTS` if it has its own font pair).
2. `src/lib/styles.ts`: add it to `STYLE_INFO` (label, one-line note, default preset, font and layout), to `STYLE_IDS` (the order people see) and to `STYLE_PALETTES` (four palettes, the first is the default).
3. `src/lib/style.ts`: add its font pair to `FONT_PAIRS`.
4. `src/lib/themes.ts`: add the palettes. Every theme defines every token.
5. `src/lib/fonts.ts`: declare the fonts the pair uses (`next/font` needs literal options).
6. `src/lib/templates.ts`: write the starter page and add it to `STYLE_STARTERS`.
7. `src/components/page/styles/<id>.tsx` and `<id>.css`: `Header`, `Tile` and `Row`. A scene (moving background) goes in `<id>-scene.tsx` and `.css`. Register all of it in `styles/index.tsx`.
8. `src/lib/og/index.tsx`: say which share-image style it uses.
9. `public/looks/<id>/`: the art and the placeholder pictures for the starter page. Add every file to `public/looks/CREDITS.md` with its source and licence. Only public domain, CC0 or art you made.
10. `src/app/lab/`: a component lab for the look, linked from `src/app/lab/page.tsx` (see `src/app/lab/night/page.tsx`).
11. Tests: a case for the starter in `tests/unit/templates.test.ts`, and any new schema behaviour in `tests/unit/schema.test.ts`. Run `npm run schema` afterwards.

To check it, run `npm run dev` and open:

- `/lab` and the look's component lab (`/lab/<id>`), in every state.
- `/lab/page/<id>?set=rich|sparse|photos|starter`, optionally with `&preset=<palette>` and `&layout=bento|list|canvas`. Check every palette, on desktop and on a phone.
- `node scripts/page-shot.mjs <id> <set> [width] [preset]` for a full-page screenshot in `.scratch/shots/` (it needs the dev server running on port 3200: `npx next dev -p 3200`).

## Design guidelines

- Pastel and calm. No hard borders, no loud gradients, no badges or pills.
- Motion is soft and fast; everything respects `prefers-reduced-motion`.
- Check every change in a light and a dark theme, on desktop and on a phone.

## Pull requests and releases

- Keep pull requests small. Fill in the template, and add a screenshot for anything visual.
- Add a line to `CHANGELOG.md` under "Unreleased" for user-facing changes.
- CI runs typecheck, unit tests, build, end-to-end tests and CodeQL. All must pass.
- Releases use one version number: `package.json`, `server.json`, `plugin/**/plugin.json` and `.claude-plugin/marketplace.json` change together, and `CHANGELOG.md` gets a dated heading.
- Questions and ideas: [GitHub Discussions](https://github.com/Himanshu-Sangshetti/posy/discussions). Docs: [docs.posy.page](https://docs.posy.page).