mapples 0.2.0-beta.5 → 0.2.0-beta.6

package/templates/claude/skills/mapples-design/reference/style-guides.md

@@ -0,0 +1,92 @@
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+# Style guides (phase 1)
+
+Ported from the Creator's design setup (`service--mapples-ai` `design/generate.ts`): first art
+directions, then one compact style guide per direction. The user picks one; the full token set
+(phase 2) realizes exactly that guide.
+
+## 1. Art directions
+
+Act as a creative director choosing art directions for this mobile app's design system.
+
+Propose exactly **3** art directions FOR THIS PRODUCT — grounded in its domain, audience and
+mood, never a generic template menu. Make them genuinely different from each other: vary palette
+temperature, typography class (serif / geometric sans / humanist sans / rounded / mono accents),
+shape language (sharp ↔ pill), and density (airy ↔ compact). Each direction: a short evocative
+name (2–40 chars, e.g. "Neon Court") and one tight clause (≤ 25 words) of concrete visual moves:
+palette temperature, typography class, shape language, density.
+
+## 2. Style guide per direction
+
+Act as a senior product designer sketching a compact style guide for this mobile app, for ONE
+direction at a time. Make it unmistakably different from the other directions and from a
+default blue Material palette.
+
+Rules:
+
+- Colors are hex. The preview maps are BOTH light and dark; dark is a real dark design (dark
+  surfaces, lighter text), not an inversion. `text` must have ≥ 4.5:1 contrast against
+  `background`; `onPrimary` against `primary` likewise.
+- Fonts come ONLY from the bundled library (family + weight). Pick pairings that fit the
+  direction; body fonts must be sans or a highly legible serif.
+- `iconFamily` comes ONLY from the icon library. Pick the pack whose stroke weight and shape
+  language match the direction (thin strokes for airy directions, solid glyphs for bold ones).
+- `instructions` are the seed for the FULL design system generated later: palette logic,
+  typography roles, shape language (including the elevation language — soft shadows vs flat
+  borders/contrasting surfaces, with flat a first-class choice — and radius feel), spacing feel,
+  component character, one explicit don't. Concrete, 60–100 words, no marketing language.
+
+Shape of one guide (write it into `design.md` when chosen):
+
+```md
+### <Name> — <direction in a few words>
+Rationale: <one sentence why it fits the product>
+Preview light: background #… card #… text #… textMuted #… primary #… onPrimary #… accent #…
+Preview dark:  background #… card #… text #… textMuted #… primary #… onPrimary #… accent #…
+Radius: <0–32>  ·  Fonts: headline <Family Weight> / body <Family Weight> / button <Family Weight>
+Icon family: <key>
+Instructions: <60–100 words>
+```
+
+## Font library
+
+`"<Family>-<Weight>"` is the registered React Native family name (`Manrope-SemiBold`). Weights:
+Regular, Medium, SemiBold, Bold unless noted.
+
+| Family | Category | Character | Pairs with |
+| --- | --- | --- | --- |
+| Inter | sans | neutral, highly legible UI sans | Playfair Display, Fraunces, IBM Plex Mono |
+| Manrope | sans | modern geometric, friendly tech | Fraunces, Inter, IBM Plex Mono |
+| DM Sans (`DMSans`) | sans | low-contrast geometric, calm product UI | Playfair Display, Fraunces |
+| Plus Jakarta Sans (`PlusJakartaSans`) | sans | rounded geometric, startup/fintech | Inter, Fraunces |
+| Poppins | sans | round geometric, playful consumer apps | Nunito, Inter |
+| Nunito | sans | soft rounded terminals, approachable | Poppins, Outfit |
+| Space Grotesk (`SpaceGrotesk`) | sans | quirky technical grotesk, dev tools | Inter, IBM Plex Mono |
+| Sora | sans | wide geometric display sans, bold headlines | Inter, DM Sans |
+| Outfit | sans | clean geometric display, fashion/lifestyle | DM Sans, Nunito |
+| Playfair Display (`PlayfairDisplay`) | serif — Regular/SemiBold/Bold | high-contrast editorial serif for headlines | Inter, DM Sans |
+| Fraunces | serif — Regular/SemiBold/Bold | soft wonky serif, warm and characterful | Manrope, Inter, DM Sans |
+| IBM Plex Mono (`IBMPlexMono`) | mono — Regular/Medium | monospace for code, data and labels | Inter, Space Grotesk |
+
+## Icon library
+
+| Key | Character |
+| --- | --- |
+| ionicons | iOS-flavored rounded glyphs with filled and -outline pairs; safe modern default |
+| material-icons | Google Material: solid, geometric, compact |
+| material-design-icons | community Material superset; huge coverage, filled and outline variants |
+| feather | thin 2px stroke outlines; minimal and airy |
+| lucide | Feather's successor; consistent strokes, wide coverage |
+| ant-design | clean enterprise outlines; restrained and precise |
+| entypo | thick rounded solid glyphs; friendly and bold |
+| octicons | GitHub's set; crisp outlines tuned for small sizes |
+| fontawesome5-solid | Font Awesome 5 solid: heavy filled, classic |
+| fontawesome6-solid | Font Awesome 6 solid: heavy filled, modern |
+| simple-line-icons | ultra-light elegant line icons |
+
+The icon family is a project setting in Creator; from code, `Icon iconName="…"` uses the glyph
+names of that family (ionicons names like `home-outline`, `search`, `chevron-forward` when in
+doubt). An unknown name renders as a broken glyph — prefer a common name over a guessed one.
+
+> Not ported (Creator-only): the streaming preview cards, the `repairViolations` pass and the
+> four-guide generation count (three here, so the table fits a chat reply).

package/templates/claude/skills/mapples-sync/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: mapples-sync
+description: Running `mapples sync` from an agent — the --yes --json invocation, the JSON report fields, exit codes 0/1/2/3/4, and what to do on conflicts, deprecated files, NON_LITERAL_PROP warnings, read-scoped keys and offline runs. Use before and after every sync in a Mapples-linked app.
+---
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run mapples agent install --force to refresh -->
+# mapples sync
+
+`mapples sync` is the only way changes reach Creator. Run it from the app root as
+
+```bash
+mapples sync --yes --json
+```
+
+- `--yes` accepts every adoption proposal (new route files, pages, components) without a prompt —
+  required, because you have no TTY. Add `--no-adopt` to push edits to managed files only and
+  leave new files untouched (e.g. a helper you do not want on the canvas yet).
+- `--json` prints one JSON report and nothing else. Always parse it; never rely on the exit
+  code alone.
+- The CLI is on the app's `devDependencies`; use `npx mapples …` (or `yarn mapples …`) when the
+  bare command is not on the PATH.
+
+## What one run does
+
+1. Adopts new files (`--yes`): react-native primitives become `@mapples/ui` elements with
+   `styled` props; a new file under the routes dir joins the navigator of its directory (a new
+   `(group)/` with a generated-header `_layout.tsx` becomes its own navigator).
+2. Extracts every managed file; elements without `$sid` are tagged and the file is rewritten.
+3. Pulls Creator's changes since the last sync, 3-way merges per element and prop, writes remote
+   changes into your files surgically.
+4. Pushes your edits as JPATCH transactions (retrying on 409), updates `.mapples/head`,
+   `pages.json`, `components.json`, `base/`.
+
+## The report
+
+```json
+{
+  "pulledOps": 0, "pushedOps": 42, "head": "b3:…", "offline": false, "exitCode": 0,
+  "files": [{ "file": "app/index.tsx", "action": "updated", "detail": "tagged 12 new element(s)" }],
+  "conflicts": [{ "file": "app/index.tsx", "sid": "nd_…", "reason": "same-prop", "props": ["text"], "deprecatedTo": "app/_depr_20260916120000_index.tsx.old", "detail": "…" }],
+  "warnings": [{ "file": "app/index.tsx", "kind": "NON_LITERAL_PROP", "sid": "nd_…", "prop": "text", "detail": "…" }],
+  "dropped": [{ "index": 3, "id": "nd_…", "reason": "…", "op": { "op": "update", "entity": "RenderNode" } }],
+  "serverWarnings": ["CHILDREN_REBASED …"],
+  "notes": ["navigation: app/(main)/ had no navigator — created tabs navigator “Main” on “Root” (kind read from its _layout.tsx)"]
+}
+```
+
+| Field | Read it as |
+| --- | --- |
+| `files[].action` | `created` / `updated` / `regenerated` (from Creator after a conflict) / `deprecated` (your version moved to `_depr_…`) |
+| `conflicts[]` | both sides changed the same prop or one deleted what the other edited — the file was deprecated and regenerated |
+| `warnings[]` | lossy steps: `NON_LITERAL_PROP` (an expression prop stays code-only), `UNKNOWN_ELEMENT_WITH_SID`, … |
+| `dropped[]` | ops the server skipped (target gone) — the change did not land |
+| `serverWarnings[]` | e.g. `CHILDREN_REBASED`: the server reordered children after a concurrent edit |
+| `offline` | true = nothing reached the server; ops parked in `.mapples/outbox/` and drained next run |
+| `notes[]` | navigator creation, agent-lease heartbeat misses, rebases |
+
+## Exit codes
+
+| Code | Meaning | Do |
+| --- | --- | --- |
+| 0 | synced | read `pushedOps`, `files`, `warnings` |
+| 1 | error (bad key, malformed file, server refusal) | read stderr; fix the cause; never retry blindly |
+| 2 | synced **with conflicts** | for every `conflicts[]` entry: diff `deprecatedTo` against the regenerated file, re-apply your intent onto the new file, sync again |
+| 3 | agent lease gone (from `mapples agent …`) | stop working, tell the user Creator disconnected the agent |
+| 4 | project busy (from `mapples agent start`) | another agent session holds the project — ask before `--takeover` |
+
+## After a sync
+
+- **Re-read every file the report lists** before editing it again — `$sid`s were added, Creator's
+  edits were written in, the marker may have moved.
+- `NON_LITERAL_PROP` on something you meant to be a literal: replace the expression with the
+  literal value (`text={title}` → `text="Today"`), sync again.
+- A `deprecated` file with no conflict entry means the CLI had to own that position (a layout
+  you wrote without the generated header): let the generated file stand.
+- `pushedOps: 0` after you changed a managed file means the extraction saw nothing: check that
+  the elements are Mapples imports with literal props, and that the file has no syntax error
+  (the report lists `SYNTAX_ERROR` warnings).
+- `offline: true`: run again once online; do not edit `.mapples/outbox/`.
+
+## Errors you may see
+
+- `push rejected: API key is read-scoped …` — the `MAPPLES_SECRET` / `.mapples/secret` key can
+  only read. Ask the user for a read & write key (Creator → Project → Settings → API keys) and
+  to restart with `MAPPLES_SECRET=<key> claude`; do not edit `.mapples/secret` yourself.
+- `no .mapples/config.json` — you are not in the app root, or the app is not linked; do not run
+  `mapples init` on your own — ask.
+- `HEAD_MISMATCH … could not be committed after 5 rebases` — Creator is being edited at the same
+  time; wait a moment and sync again.
+
+Never delete `.mapples/head`, `.mapples/base/`, `.mapples/pages.json` or `.mapples/components.json`
+to "fix" a sync — that discards the merge base and turns the next run into a cold bootstrap that
+can deprecate every file.

package/templates/gitignore

@@ -7,3 +7,5 @@ web-build/
 .mapples/outbox/
 # project API secret — never commit
 .mapples/secret
+# agent-session lease state — local only
+.mapples/agent.json

package/templates/package.json

@@ -11,6 +11,7 @@
   },
   "dependencies": {
     "@mapples/action": "^1.1.2",
+    "@mapples/components": "^1.2.1",
     "@mapples/form": "^1.2.0",
     "@mapples/inlang": "^1.2.0",
     "@mapples/render": "^1.2.0",