mapples 0.2.0-beta.5 → 0.2.0-beta.7

package/templates/claude/skills/mapples-design/reference/playbooks/visual-hierarchy.md

@@ -0,0 +1,18 @@
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
+# Visual hierarchy
+
+Cross-screen craft: one focal point, the type ladder, grouping, squint-test review.
+
+A screen reads in ONE glance-order: focal point → supporting context → actions. Design that order deliberately; never let it emerge by accident.
+
+The focal point: exactly one per screen — the Headline, the hero photo, or the big number. Everything else steps down. Two elements fighting for attention (two Headlines, a hero photo AND a huge stat) is the most common failure: pick one, demote the other a full ladder step.
+
+The type ladder is strict: Headline (page title / hero claim, once) → Subtitle (section titles) → Body (reading text) → Label (row titles, buttons) → Caption (meta, secondary) → Overline (section eyebrows, uppercase). Never skip sideways — a section title is always Subtitle, a row title always Label, on every screen of the app. Emphasis inside a level comes from color (`theme.text.primary` vs secondary vs tertiary), not from inventing new sizes.
+
+Grouping is proximity before boxes: related items sit close (gap 4–8), groups separate wide (24–32). Reach for a card or divider only when spacing alone cannot carry the grouping. Within a group, align to ONE left edge; icon centers align to the text they accompany.
+
+Weight discipline: at most two font weights visible per screen region. Color accents (`theme.primary.main`) mark interactive or key items ONLY — an accent on decoration teaches users to ignore it.
+
+The squint test (run it on every re-read of a finished file): blur your eyes at the screen as the phone would draw it. You should still see WHERE to look first and WHAT is tappable. If everything blurs into even gray noise, the hierarchy is flat — raise the focal point, quiet the rest. If one block screams that is not the primary action, swap emphasis.
+
+Pitfalls: three or more text sizes inside one card; every row shouting in bold; accents on more than ~10 percent of the screen; centered text mixed with left-aligned text in the same block.

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

@@ -0,0 +1,92 @@
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ 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,93 @@
+---
+name: mapples-sync
+description: Running `npx -y mapples@__CLI_VERSION__ 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 npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
+# npx -y mapples@__CLI_VERSION__ sync
+
+`npx -y mapples@__CLI_VERSION__ sync` is the only way changes reach Creator. Run it from the app root as
+
+```bash
+npx -y mapples@__CLI_VERSION__ 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.
+- Always run the CLI exactly as written here, pinned to the version that generated these skills:
+  `npx -y mapples@__CLI_VERSION__ …`. Never a bare `mapples` and never an unpinned `npx mapples` — npm's
+  `latest` tag can be an older CLI without these commands, and a fallback silently runs it.
+
+## 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 `npx -y mapples@__CLI_VERSION__ agent …`) | stop working, tell the user Creator disconnected the agent |
+| 4 | project busy (from `npx -y mapples@__CLI_VERSION__ 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
+  `npx -y mapples@__CLI_VERSION__ 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",
@@ -34,16 +35,17 @@
     "@react-native-vector-icons/octicons": "^21.1.0",
     "@react-native-vector-icons/simple-line-icons": "^13.1.0",
     "@react-native-vector-icons/zocial": "^13.1.0",
-    "expo": "~57.0.19",
-    "expo-constants": "~57.0.17",
-    "expo-font": "~57.0.3",
-    "expo-linear-gradient": "~57.0.1",
-    "expo-linking": "~57.0.9",
-    "expo-router": "~57.0.18",
-    "expo-splash-screen": "~57.0.8",
+    "expo": "~57.0.23",
+    "expo-constants": "~57.0.18",
+    "expo-font": "~57.0.4",
+    "expo-image": "~57.0.5",
+    "expo-linear-gradient": "~57.0.2",
+    "expo-linking": "~57.0.10",
+    "expo-router": "~57.0.21",
+    "expo-splash-screen": "~57.0.9",
     "expo-status-bar": "~57.0.1",
-    "expo-system-ui": "~57.0.3",
-    "expo-web-browser": "~57.0.2",
+    "expo-system-ui": "~57.0.4",
+    "expo-web-browser": "~57.0.3",
     "jsbarcode": "^3.12.3",
     "react": "19.2.3",
     "react-dom": "19.2.3",
@@ -53,7 +55,7 @@
     "react-native-reanimated": "4.5.1",
     "react-native-safe-area-context": "~5.7.0",
     "react-native-screens": "~4.26.0",
-    "react-native-svg": "15.15.5",
+    "react-native-svg": "15.15.4",
     "react-native-web": "~0.21.0",
     "react-native-worklets": "0.10.1"
   },