@cavulsqa/create 2.9.3 → 2.10.0

package/templates/m3e-app/.claude/rules/database.md

@@ -0,0 +1,106 @@
+# Schema and migrations
+
+`src/shared/database/schema.ts` is what Kysely type-checks every query against.
+`src/shared/database/migrations.ts` is what actually creates the tables. The two are edited
+together, always: a field in one and not the other is a runtime error the compiler cannot see.
+
+## Migrations
+
+- Keys are ordered lexically and recorded once applied, so they are **numbered and never renamed**.
+  Renaming one makes it run again on a database that already has it.
+- Never edit a migration that has shipped. Add the next one.
+- A synced table is created with `createTableWithDefaults` when it carries the sync contract, or a
+  plain `createTable` when it does not. This template has no server, so plain tables are the norm.
+- Declare foreign keys, and index the columns screens filter and join by. Without them every
+  dashboard aggregate is a full scan, which you will not notice until the table is large and the
+  device is slow.
+- SQLite ignores foreign keys unless asked; `PRAGMA foreign_keys = ON` runs at the end of the
+  migration. It is per-connection, so a cascade is not something to rely on — `deleteOrder` removes
+  the lines explicitly.
+
+## Types
+
+- Money is **integer cents**, named `*_cents`. A float total is a rounding bug waiting for a
+  large-enough order.
+- Timestamps are ISO strings via `nowISO()`.
+- A price copied onto an order line is copied deliberately, so a later catalogue change does not
+  rewrite history.
+
+## Getting an inserted id
+
+Use `insertId`, never `.returning(...)`:
+
+```ts
+const inserted = await trx.insertInto("sales_order").values({ ... }).executeTakeFirstOrThrow();
+const orderId = Number(inserted.insertId ?? 0);
+if (!orderId) throw new Error("the order was written but the database reported no id for it");
+```
+
+`insertId` is the portable answer. Every engine reports it — the worker engines from
+`last_insert_rowid()`, the sql.js test dialect the same way — so a repository written against it
+behaves identically in tests and on a device. `.returning(...)` does work on the worker engines, but
+it is the one thing that differs between them: the Capacitor plugin runs a statement issued inside an
+open transaction through `query()`, which executes it and silently drops its RETURNING rows, so
+`.returning("id").executeTakeFirstOrThrow()` threw `no result` from an insert that had in fact
+succeeded. `@cavulsqa/mobile-db` now throws a message that says so instead.
+
+## The web path is the device path
+
+Both run the same engine: SQLite compiled to WebAssembly, in a worker, with the database file in
+OPFS. There is no Capacitor SQLite plugin in this template and no sql.js outside the tests. So:
+
+- **Browser data survives a reload.** OPFS is durable storage, not memory. Clear it from
+  Diagnostics, or through the browser's site-data controls.
+- A bug reproduced in the browser is very likely the same bug as on the device, which was not true
+  when the two ran different engines.
+- `localStorage["app.storage.force"]` pins the chain to one engine id, for comparing them.
+
+What still does not transfer is **timing**. A phone's storage and CPU are nothing like a laptop's,
+and the worker is serial either way, so a ratio measured in a browser says nothing about the device.
+Run the Diagnostics benchmark on hardware.
+
+## Proof obligations
+
+A schema change needs a test in `tests/` that runs the migration and the affected queries against
+sql.js. `tests/sales.repository.test.ts` is the pattern: build a Kysely on `createSqlJsDialect()`,
+migrate, then assert on real rows — including the arithmetic. A total that type-checks can still be
+computed wrong.
+
+## Writing a lot of rows
+
+Measured on a phone, at 100k rows, per row written:
+
+| how                                              | per row        |
+| ------------------------------------------------ | -------------- |
+| one insert per statement, each its own commit    | 8-13 ms        |
+| one insert per statement, inside one transaction | ~0.45 ms       |
+| multi-row insert, ~150 rows per statement        | 0.066-0.115 ms |
+
+Roughly a hundredfold between the worst and best way to write the same row. SQLite caps parameters
+per statement, so 150 rows of five columns is about the practical ceiling for one insert - chunk by
+parameter budget, not by a round number.
+
+## Why a big write freezes the screen, and what to do
+
+The database runs in one worker, and that worker is serial. A read cannot overtake a write already
+in flight; it waits for everything queued ahead of it. So the cost to the UI is not how fast the
+write is, it is **how much work the write committed to before the read arrived**.
+
+Time a screen's read waits when it lands during a 1000-row write:
+
+| write strategy                                 | read waits    |
+| ---------------------------------------------- | ------------- |
+| 1000 single inserts in one transaction         | ~350-690 ms   |
+| 150 rows per statement, one transaction        | ~36-53 ms     |
+| ten transactions of 100, awaited one at a time | **~21-32 ms** |
+
+A naive loop stalls the screen for most of a second. Chunked transactions bring it under the
+threshold anyone notices, and the reason is mechanical: awaiting each chunk means only one chunk is
+ever queued, so an arriving read waits for 100 rows instead of 1000.
+
+**So: write in chunks of about a hundred rows, use multi-row inserts inside each chunk, and await
+each chunk before starting the next.** Do not wrap a thousand rows in one transaction to be fast -
+it is faster in total and far worse for anyone looking at the screen while it runs.
+
+The Diagnostics benchmark measures all three strategies, so this is checkable on any device rather
+than taken on faith.

package/templates/m3e-app/.claude/rules/m3e-ui.md

@@ -0,0 +1,48 @@
+# UI: Material 3 Expressive on a Framework7 engine
+
+The full workflow is the `m3-expressive` skill. These are the guardrails it rests on, each one a way
+the screen breaks silently.
+
+## Framework7 is the engine, not the look
+
+Only five Framework7 components resolve: `F7App`, `F7Views`, `F7View`, `F7Page`, `F7PageContent`
+(the allowlist in `src/shared/utils/resolvers/resolvers.ts`). Routing, per-tab history and page
+events come from them; everything visible is an `M3*` component. A visual `f7-*` component brings
+Framework7's styling and modal stack back and fights the M3 overlay stack for Android back.
+
+`f7`, `f7ready` are auto-imported; `f7route` / `f7router` arrive as props of a route component:
+`defineProps<{ f7route: Router.Route; f7router: Router.Router }>()`. Inside shared components, reach
+the router with `useViewRouter(el)`.
+
+## CSS is layered
+
+`assets/css/app.css` declares `@layer framework7, theme, base, components, utilities`. Framework7's
+CSS is the lowest layer and the M3 components sit below Tailwind's utilities, so a utility on a
+component always wins and `!important` is never needed. New global CSS goes in a layer; component
+CSS goes in the component's `<style scoped>`.
+
+Layers only settle conflicts: a Framework7 rule nothing else contradicts still applies. Its core
+sizes every bare `button` to `width: 100%` - the M3 components undo it for their own buttons, so a
+hand-made `<button>` must set its width or use an `M3*` button.
+
+In `<style scoped>`, wrap the whole selector: `:global(.parent .child)`. Vue compiles
+`:global(.parent) .child` to `.parent` alone, silently styling the wrong element.
+
+## Tokens only
+
+Tailwind's default palette, radii, shadows and easings are cleared in
+`assets/css/theme/tailwind.css` and refilled from `--md-sys-*`. A class like `bg-red-500` does not
+exist. Colours: roles. Corners: the shape scale. Type: `type-*`. Hex values live in
+`src/app/theme.config.ts` only.
+
+## Icons are SVG components, checked at build time
+
+`<i-ms-<name>-rounded />` from Material Symbols (outlined: `-outline-rounded`, filled: `-rounded`).
+`autoInstall` is off, so a wrong name fails the build instead of rendering nothing. In TS:
+`import Icon from "~icons/material-symbols/<name>"` and `markRaw` it before putting it in reactive
+state.
+
+## Proof obligations
+
+`vp check`, `pnpm type-check` and `vp test` pass. Say what you saw run - light and dark, compact width,
+reduced motion - and say plainly when you have not seen it on a device.

package/templates/m3e-app/.claude/rules/modules.md

@@ -0,0 +1,43 @@
+# Modules, domains and shared
+
+```
+modules/<feature>/router/routes/<feature>.routes.ts   default export, Router.RouteParameters[]
+modules/<feature>/views/<Name>View.vue                thin, presentational
+modules/<feature>/components/*.vue                    props in, emits out
+modules/<feature>/composables/use*.ts                 the feature's state and actions
+domains/<domain>/<domain>.repository.ts               SQL only
+shared/…                                              what two modules genuinely both need
+```
+
+## The seam
+
+A **view** wires a composable to components. If it holds business logic, that logic belongs in the
+composable; if it holds SQL, that belongs in a repository.
+
+A **composable** owns state, queries and actions for one feature. It may import repositories and
+the reactive query helpers. It returns refs and functions, never markup.
+
+A **repository** is plain functions over Kysely. No `ref`, no lifecycle, no Framework7, no imports
+from `modules/`. It takes the database as a parameter — that is what makes it testable, and reaching
+for the singleton instead is what made the first version of this template untestable.
+
+A **component** takes props and emits events. It does not query the database.
+
+## Direction of dependencies
+
+`modules → domains → shared → packages`. Never backwards. A repository importing from a module, or
+`shared` importing from `modules`, means something is in the wrong place.
+
+## Adding a feature
+
+1. `modules/<feature>/` with the four folders.
+2. Its routes in `router/routes/<feature>.routes.ts`, registered in `src/router/index.ts` before the
+   global catch-all.
+3. A tab in `src/app/tabs.ts` only if it is a top-level section. Otherwise it is a pushed page, and
+   pushed pages are an `AppPage` with `back`, which hides the navigation bar.
+4. Strings in **both** `locales/en.json` and `locales/fr.json`. A missing key renders the key.
+
+## shared/ is not a junk drawer
+
+Something goes in `shared/` when two modules import it today. Not when one module might later. The
+test is: can you name the second caller? If not, it lives in the module that uses it.

package/templates/m3e-app/.claude/rules/native.md

@@ -0,0 +1,60 @@
+# Capacitor and native behaviour
+
+Every native call is guarded with `Capacitor.isNativePlatform()` or
+`Capacitor.getPlatform() === "web"`. `vp dev` in a browser must keep working — it is how the app is
+inspected — so a handler that assumes a device breaks the fastest feedback loop you have.
+
+Native wiring that needs the Framework7 instance runs inside `f7ready`, not at module load.
+`src/plugins/capacitor/index.ts` is the single entry point.
+
+## What is already handled, and why it is not simple
+
+- **Back button** (`useAndroidBackButton`) first asks the M3 overlay stack to close its topmost
+  overlay (sheet, dialog, menu, FAB menu) - a persistent one swallows back instead. Then the current
+  tab's history, then from another tab's root the start destination, then it minimises rather than
+  exits. Overlays register themselves through `useOverlay`; a hand-built modal is invisible to back.
+- **Keyboard** (`useKeyboard`) scrolls the focused input into view on _every_ phase of the
+  transition, not once — the layout is still settling at `keyboardWillShow` and only
+  `keyboardDidShow` sees the final height. It also hides the navigation bar, which otherwise steals a
+  row from the field being typed into.
+- **Status bar** overlays the web view (edge to edge); the top app bar pads itself with the inset,
+  and the icon colour follows the theme's dark mode.
+- **Splash** stays up until `hideSplashScreen()`, called on a frame boundary so there is no flash of
+  an unpainted shell.
+
+Do not simplify these into a single listener. Each branch is there because of a specific device
+behaviour, and the comments say which.
+
+## The bootstrap must never fail silently
+
+`main.ts` opens the database before mounting, inside a `try`, and renders the failure on the page if
+it throws. An earlier version awaited it at module top level: a rejection produced an empty `#app`
+and a completely silent console, which is the worst possible failure for whoever generates from this
+template. The timeout exists so a hang cannot masquerade as a blank screen either.
+
+Anything else added to the bootstrap follows the same shape: guarded, and loud when it fails.
+
+## Fixed elements and the shell
+
+The compact navigation bar floats over the bottom of the views; the shell publishes its height as
+`--app-nav-offset` and `--app-bottom-inset` (offset plus the gesture area). So:
+
+- Anything floating above content offsets by `--app-bottom-inset` - `AppPage`'s `#fab` slot, the
+  snackbar host and the floating toolbar already do. Never measure the bar.
+- Page content is already padded by the same variable; do not add your own bottom spacer for it.
+- The FAB menu opens upward, away from the bar.
+
+## Permissions live in a generated folder
+
+`android/` is generated by `cap add android` and gitignored, so a permission the app needs is not
+carried by the template. Add it to `android/app/src/main/AndroidManifest.xml` after generating:
+
+- **Location** (the chat's _Location_ attachment): `ACCESS_COARSE_LOCATION` and
+  `ACCESS_FINE_LOCATION`. The web view's own `navigator.geolocation` does the lookup; Capacitor
+  asks the person at runtime only for a permission the manifest declares, so without these the
+  lookup fails as `denied` and the chat offers the depot instead.
+
+## Proof obligations
+
+Say which platform you tested on. "Type-checks" is not a claim about a device, and neither is a
+browser. If you have not run it on Android, say so.

package/templates/m3e-app/.claude/skills/m3-expressive/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: m3-expressive
+description: Material 3 Expressive UI in this app. Use for any screen, component, layout, animation, transition, sheet, dialog, menu, list, button, progress or loading state, colour or theme change, icon, or app-bar work - before writing markup.
+---
+
+# Material 3 Expressive
+
+This app is Material 3 Expressive end to end. Framework7 is only the navigation engine (router, tab
+views, page lifecycle); everything visible is an `M3*` component from `@cavulsqa/m3e-vue`, styled by
+`--md-sys-*` tokens from `@cavulsqa/m3e`. Expressive is not decoration: shape, spring and tonal
+colour say _what is happening_ - a selection rounds off, a sheet springs, progress waves while work
+moves. Every number comes from Google's Compose tokens; [sources.md](sources.md) links each spec.
+
+## Building a screen
+
+1. **Name the job in one sentence** and the nearest Google app that does it (Messages, Photos,
+   Settings, Files, Wallet). Open its pattern on m3.material.io from [sources.md](sources.md).
+2. **Pick the component** from [components.md](components.md). Every visible element is an `M3*`
+   component or Tailwind layout around one. Missing a component? It belongs in
+   `packages/m3e-vue`, built from its spec page - not a one-off in a module.
+3. **Wrap the route in `AppPage`** (`shared/components/page`): tab roots get the large flexible app
+   bar, pushed pages pass `back`. Layout rules: [layout.md](layout.md).
+4. **Choose shape, colour role and motion** - [shapes-type.md](shapes-type.md),
+   [color.md](color.md), [motion.md](motion.md). Each decision names its token.
+5. **Strings in both locales**, icons from Material Symbols (`<i-ms-name-rounded />`), filled
+   variant for a selected state.
+6. **Done means**: `vp check`, `pnpm type-check` and `vp test` pass; you checked light, dark, a 360dp
+   width, reduced motion, and RTL by reasoning or on screen; and you said plainly whether you saw it
+   run. Type-checking proves nothing about how a screen looks.
+
+## The rules every screen keeps
+
+- **Tokens only.** Colour is a role (`bg-surface-container-low`, `text-on-primary-container`),
+  corners are the shape scale (`rounded-lg`, `rounded-xl`), type is a style (`type-title-medium`),
+  shadows are levels (`shadow-1`..`shadow-5`). Tailwind's own palette is deleted from the theme, so
+  only roles resolve; a hex value belongs in `src/app/theme.config.ts` and nowhere else.
+- **Pairs travel together.** A container role always carries its `on-` role:
+  `bg-tertiary-container text-on-tertiary-container`. Text on a surface is `text-on-surface` or
+  `text-on-surface-variant`.
+- **Surfaces stack by container tone**, not by shadow: page `surface`, grouped content
+  `surface-container-low`, raised panels `surface-container`/`-high`. Shadows only on what floats.
+- **Overlays come from the services**: `useSnackbar`, `useDialog`, `useActionSheet` (auto-imported),
+  or `M3BottomSheet`/`M3Menu` with `v-model:open`. They register on the overlay stack, so Android
+  back and Escape close the top one. Never hand-build a modal.
+- **One tap target per row.** A list row's own button lives in `M3ListItem`'s `#action` slot, never
+  inside a clickable row.
+- **Motion is spatial or effects.** Position, size and shape use the spatial springs; colour and
+  opacity the effects springs. Never animate `width`/`top` of a large surface - `transform` and
+  `opacity`.
+- **Reduced motion keeps meaning, drops travel**: morphs and fades stay, rotation, bounce and slide
+  go. The tokens collapse spatial durations to 1 ms for you; JS-driven motion reads
+  `useReducedMotion()`.
+- **Every control is labelled**: icon buttons, FABs and switches take `label`; it becomes the
+  accessible name and tooltip.
+- **Empty is a state, not a blank.** `EmptyState` (shape, one sentence, the one action that fills it).
+  Waits under ~5 s show `M3LoadingIndicator`; known progress shows the wavy indicators.
+
+## Where things live
+
+| Need                          | Use                                                              |
+| ----------------------------- | ---------------------------------------------------------------- |
+| A screen                      | `AppPage` + modules/`<feature>`/views                            |
+| Section label                 | `SectionHeader`                                                  |
+| Theme state                   | `useThemeSettings()` - seed, variant, contrast, mode, motion     |
+| Shell navigation              | `useActiveTab()` (`show`, `open(tab, path)`), `useWindowClass()` |
+| Hide the bar on a pushed page | `AppPage back` does it; elsewhere `useHiddenNavigation()`        |
+| Decorative tone for a shape   | `TONE_CLASSES` from `shared/utils/tone`                          |
+| Live component examples       | the Gallery tab - `modules/gallery/components/sections`          |

package/templates/m3e-app/.claude/skills/m3-expressive/color.md

@@ -0,0 +1,44 @@
+# Colour
+
+One seed (`BRAND_SEED` in `src/app/theme.config.ts`) generates every role in both modes through
+material-color-utilities' 2025 (Expressive) spec. The user can change seed, variant and contrast in
+the colour studio; `useThemeSettings()` persists it and repaints in one frame. Dark mode is a `.dark`
+class on `<html>` - both modes are always in the stylesheet, so switching regenerates nothing.
+
+## Roles to reach for
+
+| Purpose                                                     | Role                                                                 |
+| ----------------------------------------------------------- | -------------------------------------------------------------------- |
+| Page background                                             | `surface`                                                            |
+| Grouped content, list segments, cards on a page             | `surface-container-low`                                              |
+| Raised panels, the nav bar, bars over scrolled content      | `surface-container` / `-high`                                        |
+| Text fields, inactive tracks                                | `surface-container-highest`                                          |
+| Main emphasis (FAB, hero, selected nav)                     | `primary-container` + `on-primary-container`                         |
+| Strong action fill                                          | `primary` + `on-primary`                                             |
+| Selected or active but quiet (chips, list rows, indicators) | `secondary-container`                                                |
+| Contrasting accent, decorative variety                      | `tertiary-container`                                                 |
+| Snackbar, tooltips                                          | `inverse-surface` + `inverse-on-surface`, action `inverse-primary`   |
+| Errors and destructive                                      | `error`, `error-container`                                           |
+| Success, warning                                            | custom groups `success-*`, `warning-*` (theme.config `EXTRA_COLORS`) |
+| Hairlines                                                   | `outline-variant`; field borders `outline`                           |
+| Secondary text, icons                                       | `on-surface-variant`                                                 |
+
+Disabled content is `on-surface` at 38%, disabled containers `on-surface` at 10-12% - the components
+already do this.
+
+## Variants and the spec trap
+
+Material applies the 2025 rules only to **tonalSpot, expressive, vibrant, neutral**. `brand`
+(seed exact as `primary-container`, Theme Builder's "Match colour"), fidelity, content, monochrome,
+rainbow and fruitSalad silently use 2021 rules - `effectiveSpec(variant)` says which. The studio shows
+it to the user.
+
+## Rules
+
+- A new semantic colour is a custom group in `EXTRA_COLORS` (harmonised to the seed), then a role
+  name in `assets/css/theme/tailwind.css` - never a hex in a component.
+- Contrast is a user setting (standard / medium / high): never compensate a weak pair by hand-picking
+  a darker colour; fix the role choice.
+- Status needs more than colour: pair it with a shape or glyph (see `STATUS_LOOK` in the demo module).
+
+See [sources.md](sources.md) → Colour.