magic_starter
Ready-made screens for a Magic app: login, registration, password reset, email verification, two-factor, social and phone sign-in, guest sessions and handoff; a settings hub with profile, security and preference pages; teams; the magic_notifications screens in the app shell; billing over magic_payments; a support desk. Each feature is a toggle in lib/config/magic_starter.dart that defaults to false. MagicStarterServiceProvider wires it, MagicStarter is the facade (bootstrap, view, theme setters), MagicStarterConfig reads the toggles and routes, and every screen, layout and modal resolves through a string-keyed registry the host can override. The controllers call magic-starter-laravel's api/v1 routes one to one.
This skill covers magic_starter only. The Magic framework itself (container, facades, routing, Auth, Http, controllers) is the magic-framework skill; the className syntax and the W-widgets are wind-ui; the notification API (Notify) is magic-notifications, the billing contract is magic-payments, the social login bridge is magic-social-auth.
Install
flutter pub add magic_starter
dart run magic:dowel plugin:install magic_starter --no-bootstrap
dart run magic:dowel starter:install --features=registration,teams,notifications
dart run magic:dowel starter:doctor
Requires Dart >=3.13, Flutter >=3.47 and magic ^1.0.0, in an app already scaffolded with dart run magic:dowel magic:install. plugin:install registers MagicStarterDowelProvider and injects MagicStarterServiceProvider into lib/config/app.dart; pass --no-bootstrap, because the chained starter:install always gets --non-interactive, writes every feature false, and a later starter:install --features=... skips the config file that exists by then yet still reports success (recover with starter:configure, a hand edit, or --force). Run starter:install yourself: without --features it asks one question per feature, every answer defaulting to no; with it, an unlisted key is written false. It writes lib/config/magic_starter.dart, the middleware, User (and Team), a dashboard, lib/routes/app.dart, the MagicStarter.bootstrap(...) call in AppServiceProvider, the auth and guest aliases in lib/app/kernel.dart, the route registrations and the English strings in assets/lang/en.json. The package has no executable: every command is dart run magic:dowel starter:<command>. Import only package:magic_starter/magic_starter.dart (or package:magic_starter/cli.dart from a pure Dart dispatcher).
Boot rules
- Register
MagicStarterServiceProvider in providers, after AuthServiceProvider (and after NotificationServiceProvider when notifications is on): its boot() reads the session the auth provider restored and the push driver the notification provider attached. It is not auto-registered; without it MagicStarter.manager falls back to a default manager, prints one debug warning, and no auth listener, push identity or starter.* Gate ability exists.
- Call
MagicStarter.bootstrap(userFactory:, onLogout:, locales:) from AppServiceProvider.boot(). Pass the host's own userFactory: without one every screen reads MagicStarterAuthUser, and nothing fails to say so.
- The team callbacks
currentTeam, allTeams, onSwitch come as all three or none. A partial set throws ArgumentError before any setter runs; teams on without them throws StateError. Route onSwitch through MagicStarter.switchTeam('$teamId'): it switches on the backend, applies the answer's user and re-identifies the store billing rail, which a direct MagicStarterTeamController.instance.switchTeam call skips.
onLogin runs after a fresh sign-in (not a restore); onGuestClaimed gets the GuestClaimOutcome of a guest claim. Both are optional and also have setters (useLogin, useGuestClaimed).
- Register work that needs the token at sign-out with
MagicStarter.beforeLogout(hook), before this provider boots: its own hooks release the push device and revoke the token with POST /auth/logout, and a hook registered after them runs on a dead token. Each hook is bounded to five seconds and a throw is logged.
Feature rules
- A toggle is read when the manager is first resolved: a feature that is off registers no route and no view key, so
MagicStarter.view.make(key) throws StateError. Guard links and builds with MagicStarterConfig.has<Feature>Features(), never an inline Config.get.
social_login needs a bridge: MagicStarter.useSocialAuth(MagicStarterSocialAuth). Without it the provider buttons and the Connected accounts hub row never render. magic_social_auth publishes the bridge; the starter never calls its signOut(), so the bridge signs its SDK out itself.
billing needs billing.web_origin, an absolute URL with no trailing slash. Unset, Stripe rejects the relative return URL and the error is only logged: the checkout button does nothing. billing.billable is 'user' or 'team', must equal the backend's, and any other value throws StateError.
billing registers the teams.billing view key and no route. The host registers a page at MagicStarterConfig.billingRoute() (routes.billing, default /teams/billing) and puts a MagicStarterBillingController in the container first (Recipes), since the view resolves its controller and cannot construct one.
notifications makes the provider declare <notifications.external_id_prefix><user id> as the push identity on every Auth.stateNotifier change and release it on any sign-out, account deletion included. The prefix defaults to user_ and must equal the backend's MAGIC_STARTER_EXTERNAL_ID_PREFIX: a mismatch is accepted by OneSignal and delivered to nobody. A blank value resolves to user_.
support needs registerMagicStarterSupportRoutes() in the route provider; starter:install adds it only when support was chosen at install. Every support_* option needs support.
guest_auth adds no route: it shows "Continue as guest" on login, records the guest token and claims the guest's data at the next sign-in. RedirectIfAuthenticated lets a guest session through to the auth pages.
- Stored and unread:
MagicStarterConfig.requestTimeoutSeconds() and maxRetries(), and useGuestAuthEntry(). Do not build on them. useNewsletterLabel() is read by the register view alone (the checkbox label when newsletter is on), not by the profile newsletter page.
Route and middleware rules
- The route groups name the middleware
auth and guest. Register them with Kernel.registerAll({'auth': () => EnsureAuthenticated(), 'guest': () => RedirectIfAuthenticated()}); starter:install writes this into lib/app/kernel.dart.
- Call
registerMagicStarterAuthRoutes() and registerMagicStarterProfileRoutes() always, and the team, notification and support functions freely: each returns early while its toggle is off. None takes an argument.
- Paths come from config:
routes.auth_prefix (/auth), routes.profile_prefix (/settings), routes.teams_prefix (/teams), routes.notifications_prefix, routes.login, routes.home. Build links with MagicStarterConfig.*Route(), never a literal path.
EnsureAuthenticated sends a signed-out visitor to routes.login and records the location with MagicRouter.setIntendedUrl; every sign-in lands there, or on routes.home. The login and register screens also honour ?next=<in-app path>.
- Put a host page inside the starter's shell with
layout: (child) => MagicStarter.view.makeLayout('layout.app', child: child) and layoutId: MagicStarterLayoutIds.app. A different layoutId is a separate shell, which rebuilds the layout on every move between them.
View registry rules
- Override with
MagicStarter.view.register(key, builder), registerLayout('layout.app' | 'layout.guest', builder) or registerModal('modal.confirm' | 'modal.password_confirm' | 'modal.two_factor', builder), from any provider's boot(). Defaults register only when a key is free, so provider order does not matter.
- The settings surface is
settings.hub plus drill-down keys: profile.profile, settings.appearance, settings.security.password (always), settings.language, settings.timezone, settings.newsletter, settings.changelog, settings.security.two_factor, settings.security.sessions, settings.security.connected_accounts (behind their toggles). profile.settings is not a registered default key.
notifications.list and notifications.preferences live on magic_notifications' Notify.view. Registering them on MagicStarter.view mounts nothing.
- A slot adds a widget inside a shipped view:
MagicStarter.view.slot(viewKey, slotName, builder), registered before the view builds. Only the names a view reads work (header and footer on the auth views, the hub, profile.profile and the team views; formFooter on login and register; afterSection:members on teams.settings); any other name is inert.
makeLayout wraps the child in a route-keyed subtree before your layout sees it, so a replacement layout keeps the remount behaviour. Render the child inside the routed subtree, never in an Overlay entry or a nested Navigator.
dart run magic:dowel starter:publish --tag=views:<key> copies a view into lib/resources/views/starter/ and registers it in AppServiceProvider. The copy does not follow later releases; starter:doctor flags a published view nothing registers.
Every key with its condition and widget: references/views-and-layouts.md.
Theming rules
- Call
MagicStarter.useWindTheme(windTheme) (or useTheme(MagicStarterTheme)) first, then the single setters. Both unified calls reset the button and field themes, so useButtonTheme() and useFieldTheme() come after them or the host's standard is lost without an error.
- Every
use*Theme() assigns the whole struct: a field you leave out goes back to its default. Change one string with MagicStarter.formTheme.copyWith(...) or MagicStarter.modalTheme.copyWith(...); only those two sub-themes have copyWith.
- Page geometry is the host's: set
MagicStarter.manager.pageContainerClassName once from the string your own pages use (default 'max-w-7xl px-4 lg:px-8 pt-6 sm:pt-8 pb-16'), and never put a max-w-* or page px-* on a starter page or component.
- Style with the semantic aliases (
bg-surface, text-fg, bg-primary, border-color-border, ...) from MagicStarterTokens.defaultAliases, passed as WindThemeData(aliases: ...). Wind drops an alias the theme lacks silently, so the class paints nothing.
- A
className passed to an MS component is appended after the theme and wins on every family it names.
Sub-themes, the button and field arithmetic and the modal presentation: references/theming.md.
Sign-in and identity rules
- Every shipped sign-in (password, social, two-factor challenge, OTP, guest, handoff) concludes in one internal step that reads a two-factor answer at the top level or under
data, shows a cancelled deletion, logs in and lands on the intended URL. Drive a sign-in through the controllers (doLogin, doSocialSignIn, doTwoFactorChallenge, ...) rather than calling Auth.login with a token yourself, or those steps are skipped.
- Gated profile calls take
proof: (Map<String, String>): doEnableTwoFactor, doDisableTwoFactor, getRecoveryCodes, doRegenerateRecoveryCodes, doRevokeSession, doRevokeOtherSessions, doDeleteAccount, doSetPassword. A password account gives {'password': ...}, a password-less one {'code': ...} or {'confirmation_token': ...}, a guest {}. Get it with confirmIdentity(context) or run the action inside confirmAndRun(context, controller, action: ...).
- Read a refusal by its
code, never its message (step_up_required, password_already_set, last_login_method, owns_shared_teams, ...).
doDeleteAccount(proof:) schedules the deletion by default (a sign-in within the grace period cancels it); immediately: true skips the grace period. Either way the user is signed out without the before-logout hooks.
- Call
MagicStarterAuthController.instance.doSocialSignIn(provider) straight from the tap, with no await before it, or a web popup is blocked.
- A controller of yours that caches one user's or one team's data implements magic's
SessionScoped; the provider declares the session identity as user plus team, and the host calls SessionScope.attach() last in its own provider.
Recipes
Bootstrap a team app. User and Team are the host's models. With teams on, starter:install writes a Team that ships toMagicStarterTeam() and a User with the currentTeam and allTeams getters. Write the conversion yourself (an extension returning MagicStarterTeam(id:, name:, photoUrl:, isPersonalTeam:)) only when a team.dart or user.dart already existed and starter:install skipped it because --force was not passed:
import 'package:magic/magic.dart';
import 'package:magic_starter/magic_starter.dart';
class AppServiceProvider extends ServiceProvider {
AppServiceProvider(super.app);
@override
void register() {}
@override
Future<void> boot() async {
MagicStarter.bootstrap(
userFactory: (data) => User.fromMap(data),
onLogout: () async {
await Auth.logout();
MagicRoute.to(MagicStarterConfig.loginRoute());
},
locales: {
'en': 'English',
'tr': 'Türkçe',
},
currentTeam: () => User.current.currentTeam?.toMagicStarterTeam(),
allTeams: () => User.current.allTeams
.map((team) => team.toMagicStarterTeam())
.toList(),
onSwitch: (teamId) => MagicStarter.switchTeam('$teamId'),
);
}
}
Register the routes and the middleware aliases:
import 'package:magic/magic.dart';
import 'package:magic_starter/magic_starter.dart';
void registerStarterRoutes() {
Kernel.registerAll({
'auth': () => EnsureAuthenticated(),
'guest': () => RedirectIfAuthenticated(),
});
registerMagicStarterAuthRoutes();
registerMagicStarterProfileRoutes();
registerMagicStarterTeamRoutes();
registerMagicStarterNotificationRoutes();
registerMagicStarterSupportRoutes();
}
Mount the billing view (UsageStat comes from magic_payments, a direct dependency once you name it):
import 'package:magic/magic.dart';
import 'package:magic_payments/magic_payments.dart';
import 'package:magic_starter/magic_starter.dart';
void registerBilling() {
Magic.put(
MagicStarterBillingController(
usageCopy: (stats) => [
for (final stat in stats)
UsageStat(
key: stat.key,
used: stat.used,
limit: stat.limit,
label: trans('usage.${stat.key}'),
),
],
formatNumber: (value) => '$value',
),
);
if (!MagicStarterConfig.hasBillingFeatures()) return;
MagicRoute.group(
middleware: ['auth'],
layoutId: MagicStarterLayoutIds.app,
layout: (child) => MagicStarter.view.makeLayout('layout.app', child: child),
routes: () {
MagicRoute.page(
MagicStarterConfig.billingRoute(),
() => MagicStarter.view.make('teams.billing'),
);
},
);
}
Replace a screen and add a slot:
import 'package:flutter/widgets.dart';
import 'package:magic/magic.dart';
import 'package:magic_starter/magic_starter.dart';
class BrandedLoginView extends StatelessWidget {
const BrandedLoginView({super.key});
@override
Widget build(BuildContext context) => WText('Sign in', className: 'text-fg');
}
void customiseStarter() {
MagicStarter.view.register('auth.login', () => const BrandedLoginView());
MagicStarter.view.slot('settings.hub', 'footer', (context) {
return WText('v1', className: 'text-sm text-fg-muted');
});
}
Theme from the host palette, then the button and field standards:
import 'package:magic/magic.dart';
import 'package:magic_starter/magic_starter.dart';
void themeStarter(WindThemeData windTheme) {
const String standard = 'px-5 py-[11px] text-[17px] leading-[22px]';
MagicStarter.useWindTheme(windTheme);
MagicStarter.useButtonTheme(
const MagicStarterButtonTheme(
shapeClassName: 'rounded-full',
smClassName: standard,
mdClassName: standard,
lgClassName: standard,
),
);
MagicStarter.useFormTheme(
MagicStarter.formTheme.copyWith(
inputClassName: 'w-full py-[10px] min-h-11 text-[17px] leading-[22px]',
),
);
}
Run a gated action with step-up proof from a view of your own:
import 'package:flutter/widgets.dart';
import 'package:magic/magic.dart';
import 'package:magic_starter/magic_starter.dart';
Future<void> deleteAccount(BuildContext context) async {
final MagicStarterProfileController controller =
MagicStarterProfileController.instance;
await confirmAndRun(
context,
controller,
variant: ConfirmDialogVariant.danger,
action: (proof) => controller.doDeleteAccount(proof: proof),
);
}
Turn a plan-gated 403 into the upgrade prompt:
import 'package:magic/magic.dart';
import 'package:magic_starter/magic_starter.dart';
Future<void> analyse(String id) async {
final MagicResponse response = await Http.post('/monitors/$id/analyze');
if (response.successful) return;
final PlanUpgradeRequirement? requirement =
PlanUpgradeRequirement.fromResponse(response);
if (requirement != null) {
UpgradePrompt.show(requirement);
}
}
Testing
No mocking library. In setUp() call MagicApp.reset() and Magic.flush(), then setUpMagicStarterForTests() (or pass a configured MagicStarterManager), bind a contract fake for the network (Magic.singleton('network', () => FakeDriver()), a class that implements NetworkDriver and records the method, URL and payload) and set toggles with Config.set('magic_starter.features.<key>', true) before the manager is first resolved. Assert the request a controller sends and its state (controller.isSuccess, hasErrors), never a faked sign-in. MagicStarter.resetFallbackManagerForTests() clears the unbound fallback between tests. Dispose a controller's ValueNotifiers in tearDown().
References
references/views-and-layouts.md: every view, layout and modal key with its condition, the slots, the shell hooks (navigation, header, sidebar footer, page chrome, bottom nav), publishing.
references/controllers-and-routes.md: the controllers and what each owns, every route with its path and middleware, sign-in completion and session scope.
references/theming.md: the sub-themes, useWindTheme, the button and field standards, modal presentation.
references/backend-contract.md: the api/v1 endpoints each controller calls, the backend keys that must match, the refusal codes.
1---2name: magic-starter3description: "Opt-in Magic screens for sign-in, settings, teams, notifications, billing and support, with a view registry, theming and starter:* commands."4version: 1.0.05when_to_use: "Use when code imports package:magic_starter or touches MagicStarter, MagicStarterConfig, a starter view key, an MS component or a starter:* command."6metadata:7 source: https://skillmd.com/skills/anilcancakir/magic-starter8---910# magic_starter1112Ready-made screens for a Magic app: login, registration, password reset, email verification, two-factor, social and phone sign-in, guest sessions and handoff; a settings hub with profile, security and preference pages; teams; the `magic_notifications` screens in the app shell; billing over `magic_payments`; a support desk. Each feature is a toggle in `lib/config/magic_starter.dart` that defaults to `false`. `MagicStarterServiceProvider` wires it, `MagicStarter` is the facade (`bootstrap`, `view`, theme setters), `MagicStarterConfig` reads the toggles and routes, and every screen, layout and modal resolves through a string-keyed registry the host can override. The controllers call `magic-starter-laravel`'s `api/v1` routes one to one.1314This skill covers `magic_starter` only. The Magic framework itself (container, facades, routing, `Auth`, `Http`, controllers) is the `magic-framework` skill; the className syntax and the W-widgets are `wind-ui`; the notification API (`Notify`) is `magic-notifications`, the billing contract is `magic-payments`, the social login bridge is `magic-social-auth`.1516## Install1718```bash19flutter pub add magic_starter20dart run magic:dowel plugin:install magic_starter --no-bootstrap21dart run magic:dowel starter:install --features=registration,teams,notifications22dart run magic:dowel starter:doctor23```2425Requires Dart >=3.13, Flutter >=3.47 and `magic` ^1.0.0, in an app already scaffolded with `dart run magic:dowel magic:install`. `plugin:install` registers `MagicStarterDowelProvider` and injects `MagicStarterServiceProvider` into `lib/config/app.dart`; pass `--no-bootstrap`, because the chained `starter:install` always gets `--non-interactive`, writes every feature `false`, and a later `starter:install --features=...` skips the config file that exists by then yet still reports success (recover with `starter:configure`, a hand edit, or `--force`). Run `starter:install` yourself: without `--features` it asks one question per feature, every answer defaulting to no; with it, an unlisted key is written `false`. It writes `lib/config/magic_starter.dart`, the middleware, `User` (and `Team`), a dashboard, `lib/routes/app.dart`, the `MagicStarter.bootstrap(...)` call in `AppServiceProvider`, the `auth` and `guest` aliases in `lib/app/kernel.dart`, the route registrations and the English strings in `assets/lang/en.json`. The package has no executable: every command is `dart run magic:dowel starter:<command>`. Import only `package:magic_starter/magic_starter.dart` (or `package:magic_starter/cli.dart` from a pure Dart dispatcher).2627## Boot rules28291. Register `MagicStarterServiceProvider` in `providers`, after `AuthServiceProvider` (and after `NotificationServiceProvider` when `notifications` is on): its `boot()` reads the session the auth provider restored and the push driver the notification provider attached. It is not auto-registered; without it `MagicStarter.manager` falls back to a default manager, prints one debug warning, and no auth listener, push identity or `starter.*` Gate ability exists.302. Call `MagicStarter.bootstrap(userFactory:, onLogout:, locales:)` from `AppServiceProvider.boot()`. Pass the host's own `userFactory`: without one every screen reads `MagicStarterAuthUser`, and nothing fails to say so.313. The team callbacks `currentTeam`, `allTeams`, `onSwitch` come as all three or none. A partial set throws `ArgumentError` before any setter runs; `teams` on without them throws `StateError`. Route `onSwitch` through `MagicStarter.switchTeam('$teamId')`: it switches on the backend, applies the answer's user and re-identifies the store billing rail, which a direct `MagicStarterTeamController.instance.switchTeam` call skips.324. `onLogin` runs after a fresh sign-in (not a restore); `onGuestClaimed` gets the `GuestClaimOutcome` of a guest claim. Both are optional and also have setters (`useLogin`, `useGuestClaimed`).335. Register work that needs the token at sign-out with `MagicStarter.beforeLogout(hook)`, before this provider boots: its own hooks release the push device and revoke the token with `POST /auth/logout`, and a hook registered after them runs on a dead token. Each hook is bounded to five seconds and a throw is logged.3435## Feature rules36371. A toggle is read when the manager is first resolved: a feature that is off registers no route and no view key, so `MagicStarter.view.make(key)` throws `StateError`. Guard links and builds with `MagicStarterConfig.has<Feature>Features()`, never an inline `Config.get`.382. `social_login` needs a bridge: `MagicStarter.useSocialAuth(MagicStarterSocialAuth)`. Without it the provider buttons and the Connected accounts hub row never render. `magic_social_auth` publishes the bridge; the starter never calls its `signOut()`, so the bridge signs its SDK out itself.393. `billing` needs `billing.web_origin`, an absolute URL with no trailing slash. Unset, Stripe rejects the relative return URL and the error is only logged: the checkout button does nothing. `billing.billable` is `'user'` or `'team'`, must equal the backend's, and any other value throws `StateError`.404. `billing` registers the `teams.billing` view key and no route. The host registers a page at `MagicStarterConfig.billingRoute()` (`routes.billing`, default `/teams/billing`) and puts a `MagicStarterBillingController` in the container first (Recipes), since the view resolves its controller and cannot construct one.415. `notifications` makes the provider declare `<notifications.external_id_prefix><user id>` as the push identity on every `Auth.stateNotifier` change and release it on any sign-out, account deletion included. The prefix defaults to `user_` and must equal the backend's `MAGIC_STARTER_EXTERNAL_ID_PREFIX`: a mismatch is accepted by OneSignal and delivered to nobody. A blank value resolves to `user_`.426. `support` needs `registerMagicStarterSupportRoutes()` in the route provider; `starter:install` adds it only when `support` was chosen at install. Every `support_*` option needs `support`.437. `guest_auth` adds no route: it shows "Continue as guest" on login, records the guest token and claims the guest's data at the next sign-in. `RedirectIfAuthenticated` lets a guest session through to the auth pages.448. Stored and unread: `MagicStarterConfig.requestTimeoutSeconds()` and `maxRetries()`, and `useGuestAuthEntry()`. Do not build on them. `useNewsletterLabel()` is read by the register view alone (the checkbox label when `newsletter` is on), not by the profile newsletter page.4546## Route and middleware rules47481. The route groups name the middleware `auth` and `guest`. Register them with `Kernel.registerAll({'auth': () => EnsureAuthenticated(), 'guest': () => RedirectIfAuthenticated()})`; `starter:install` writes this into `lib/app/kernel.dart`.492. Call `registerMagicStarterAuthRoutes()` and `registerMagicStarterProfileRoutes()` always, and the team, notification and support functions freely: each returns early while its toggle is off. None takes an argument.503. Paths come from config: `routes.auth_prefix` (`/auth`), `routes.profile_prefix` (`/settings`), `routes.teams_prefix` (`/teams`), `routes.notifications_prefix`, `routes.login`, `routes.home`. Build links with `MagicStarterConfig.*Route()`, never a literal path.514. `EnsureAuthenticated` sends a signed-out visitor to `routes.login` and records the location with `MagicRouter.setIntendedUrl`; every sign-in lands there, or on `routes.home`. The login and register screens also honour `?next=<in-app path>`.525. Put a host page inside the starter's shell with `layout: (child) => MagicStarter.view.makeLayout('layout.app', child: child)` and `layoutId: MagicStarterLayoutIds.app`. A different `layoutId` is a separate shell, which rebuilds the layout on every move between them.5354## View registry rules55561. Override with `MagicStarter.view.register(key, builder)`, `registerLayout('layout.app' | 'layout.guest', builder)` or `registerModal('modal.confirm' | 'modal.password_confirm' | 'modal.two_factor', builder)`, from any provider's `boot()`. Defaults register only when a key is free, so provider order does not matter.572. The settings surface is `settings.hub` plus drill-down keys: `profile.profile`, `settings.appearance`, `settings.security.password` (always), `settings.language`, `settings.timezone`, `settings.newsletter`, `settings.changelog`, `settings.security.two_factor`, `settings.security.sessions`, `settings.security.connected_accounts` (behind their toggles). `profile.settings` is not a registered default key.583. `notifications.list` and `notifications.preferences` live on `magic_notifications`' `Notify.view`. Registering them on `MagicStarter.view` mounts nothing.594. A slot adds a widget inside a shipped view: `MagicStarter.view.slot(viewKey, slotName, builder)`, registered before the view builds. Only the names a view reads work (`header` and `footer` on the auth views, the hub, `profile.profile` and the team views; `formFooter` on login and register; `afterSection:members` on `teams.settings`); any other name is inert.605. `makeLayout` wraps the child in a route-keyed subtree before your layout sees it, so a replacement layout keeps the remount behaviour. Render the child inside the routed subtree, never in an `Overlay` entry or a nested `Navigator`.616. `dart run magic:dowel starter:publish --tag=views:<key>` copies a view into `lib/resources/views/starter/` and registers it in `AppServiceProvider`. The copy does not follow later releases; `starter:doctor` flags a published view nothing registers.6263Every key with its condition and widget: `references/views-and-layouts.md`.6465## Theming rules66671. Call `MagicStarter.useWindTheme(windTheme)` (or `useTheme(MagicStarterTheme)`) first, then the single setters. Both unified calls reset the button and field themes, so `useButtonTheme()` and `useFieldTheme()` come after them or the host's standard is lost without an error.682. Every `use*Theme()` assigns the whole struct: a field you leave out goes back to its default. Change one string with `MagicStarter.formTheme.copyWith(...)` or `MagicStarter.modalTheme.copyWith(...)`; only those two sub-themes have `copyWith`.693. Page geometry is the host's: set `MagicStarter.manager.pageContainerClassName` once from the string your own pages use (default `'max-w-7xl px-4 lg:px-8 pt-6 sm:pt-8 pb-16'`), and never put a `max-w-*` or page `px-*` on a starter page or component.704. Style with the semantic aliases (`bg-surface`, `text-fg`, `bg-primary`, `border-color-border`, ...) from `MagicStarterTokens.defaultAliases`, passed as `WindThemeData(aliases: ...)`. Wind drops an alias the theme lacks silently, so the class paints nothing.715. A `className` passed to an `MS` component is appended after the theme and wins on every family it names.7273Sub-themes, the button and field arithmetic and the modal presentation: `references/theming.md`.7475## Sign-in and identity rules76771. Every shipped sign-in (password, social, two-factor challenge, OTP, guest, handoff) concludes in one internal step that reads a two-factor answer at the top level or under `data`, shows a cancelled deletion, logs in and lands on the intended URL. Drive a sign-in through the controllers (`doLogin`, `doSocialSignIn`, `doTwoFactorChallenge`, ...) rather than calling `Auth.login` with a token yourself, or those steps are skipped.782. Gated profile calls take `proof:` (`Map<String, String>`): `doEnableTwoFactor`, `doDisableTwoFactor`, `getRecoveryCodes`, `doRegenerateRecoveryCodes`, `doRevokeSession`, `doRevokeOtherSessions`, `doDeleteAccount`, `doSetPassword`. A password account gives `{'password': ...}`, a password-less one `{'code': ...}` or `{'confirmation_token': ...}`, a guest `{}`. Get it with `confirmIdentity(context)` or run the action inside `confirmAndRun(context, controller, action: ...)`.793. Read a refusal by its `code`, never its message (`step_up_required`, `password_already_set`, `last_login_method`, `owns_shared_teams`, ...).804. `doDeleteAccount(proof:)` schedules the deletion by default (a sign-in within the grace period cancels it); `immediately: true` skips the grace period. Either way the user is signed out without the before-logout hooks.815. Call `MagicStarterAuthController.instance.doSocialSignIn(provider)` straight from the tap, with no `await` before it, or a web popup is blocked.826. A controller of yours that caches one user's or one team's data implements magic's `SessionScoped`; the provider declares the session identity as user plus team, and the host calls `SessionScope.attach()` last in its own provider.8384## Recipes8586Bootstrap a team app. `User` and `Team` are the host's models. With `teams` on, `starter:install` writes a `Team` that ships `toMagicStarterTeam()` and a `User` with the `currentTeam` and `allTeams` getters. Write the conversion yourself (an extension returning `MagicStarterTeam(id:, name:, photoUrl:, isPersonalTeam:)`) only when a `team.dart` or `user.dart` already existed and `starter:install` skipped it because `--force` was not passed:8788```dart89import 'package:magic/magic.dart';90import 'package:magic_starter/magic_starter.dart';9192class AppServiceProvider extends ServiceProvider {93 AppServiceProvider(super.app);9495 @override96 void register() {}9798 @override99 Future<void> boot() async {100 MagicStarter.bootstrap(101 userFactory: (data) => User.fromMap(data),102 onLogout: () async {103 await Auth.logout();104 MagicRoute.to(MagicStarterConfig.loginRoute());105 },106 locales: {107 'en': 'English',108 'tr': 'Türkçe',109 },110 currentTeam: () => User.current.currentTeam?.toMagicStarterTeam(),111 allTeams: () => User.current.allTeams112 .map((team) => team.toMagicStarterTeam())113 .toList(),114 onSwitch: (teamId) => MagicStarter.switchTeam('$teamId'),115 );116 }117}118```119120Register the routes and the middleware aliases:121122```dart123import 'package:magic/magic.dart';124import 'package:magic_starter/magic_starter.dart';125126void registerStarterRoutes() {127 Kernel.registerAll({128 'auth': () => EnsureAuthenticated(),129 'guest': () => RedirectIfAuthenticated(),130 });131132 registerMagicStarterAuthRoutes();133 registerMagicStarterProfileRoutes();134 registerMagicStarterTeamRoutes();135 registerMagicStarterNotificationRoutes();136 registerMagicStarterSupportRoutes();137}138```139140Mount the billing view (`UsageStat` comes from `magic_payments`, a direct dependency once you name it):141142```dart143import 'package:magic/magic.dart';144import 'package:magic_payments/magic_payments.dart';145import 'package:magic_starter/magic_starter.dart';146147void registerBilling() {148 Magic.put(149 MagicStarterBillingController(150 usageCopy: (stats) => [151 for (final stat in stats)152 UsageStat(153 key: stat.key,154 used: stat.used,155 limit: stat.limit,156 label: trans('usage.${stat.key}'),157 ),158 ],159 formatNumber: (value) => '$value',160 ),161 );162163 if (!MagicStarterConfig.hasBillingFeatures()) return;164165 MagicRoute.group(166 middleware: ['auth'],167 layoutId: MagicStarterLayoutIds.app,168 layout: (child) => MagicStarter.view.makeLayout('layout.app', child: child),169 routes: () {170 MagicRoute.page(171 MagicStarterConfig.billingRoute(),172 () => MagicStarter.view.make('teams.billing'),173 );174 },175 );176}177```178179Replace a screen and add a slot:180181```dart182import 'package:flutter/widgets.dart';183import 'package:magic/magic.dart';184import 'package:magic_starter/magic_starter.dart';185186class BrandedLoginView extends StatelessWidget {187 const BrandedLoginView({super.key});188189 @override190 Widget build(BuildContext context) => WText('Sign in', className: 'text-fg');191}192193void customiseStarter() {194 MagicStarter.view.register('auth.login', () => const BrandedLoginView());195196 MagicStarter.view.slot('settings.hub', 'footer', (context) {197 return WText('v1', className: 'text-sm text-fg-muted');198 });199}200```201202Theme from the host palette, then the button and field standards:203204```dart205import 'package:magic/magic.dart';206import 'package:magic_starter/magic_starter.dart';207208void themeStarter(WindThemeData windTheme) {209 const String standard = 'px-5 py-[11px] text-[17px] leading-[22px]';210211 MagicStarter.useWindTheme(windTheme);212 MagicStarter.useButtonTheme(213 const MagicStarterButtonTheme(214 shapeClassName: 'rounded-full',215 smClassName: standard,216 mdClassName: standard,217 lgClassName: standard,218 ),219 );220 MagicStarter.useFormTheme(221 MagicStarter.formTheme.copyWith(222 inputClassName: 'w-full py-[10px] min-h-11 text-[17px] leading-[22px]',223 ),224 );225}226```227228Run a gated action with step-up proof from a view of your own:229230```dart231import 'package:flutter/widgets.dart';232import 'package:magic/magic.dart';233import 'package:magic_starter/magic_starter.dart';234235Future<void> deleteAccount(BuildContext context) async {236 final MagicStarterProfileController controller =237 MagicStarterProfileController.instance;238239 await confirmAndRun(240 context,241 controller,242 variant: ConfirmDialogVariant.danger,243 action: (proof) => controller.doDeleteAccount(proof: proof),244 );245}246```247248Turn a plan-gated `403` into the upgrade prompt:249250```dart251import 'package:magic/magic.dart';252import 'package:magic_starter/magic_starter.dart';253254Future<void> analyse(String id) async {255 final MagicResponse response = await Http.post('/monitors/$id/analyze');256 if (response.successful) return;257258 final PlanUpgradeRequirement? requirement =259 PlanUpgradeRequirement.fromResponse(response);260 if (requirement != null) {261 UpgradePrompt.show(requirement);262 }263}264```265266## Testing267268No mocking library. In `setUp()` call `MagicApp.reset()` and `Magic.flush()`, then `setUpMagicStarterForTests()` (or pass a configured `MagicStarterManager`), bind a contract fake for the network (`Magic.singleton('network', () => FakeDriver())`, a class that `implements NetworkDriver` and records the method, URL and payload) and set toggles with `Config.set('magic_starter.features.<key>', true)` before the manager is first resolved. Assert the request a controller sends and its state (`controller.isSuccess`, `hasErrors`), never a faked sign-in. `MagicStarter.resetFallbackManagerForTests()` clears the unbound fallback between tests. Dispose a controller's `ValueNotifier`s in `tearDown()`.269270## References271272- `references/views-and-layouts.md`: every view, layout and modal key with its condition, the slots, the shell hooks (navigation, header, sidebar footer, page chrome, bottom nav), publishing.273- `references/controllers-and-routes.md`: the controllers and what each owns, every route with its path and middleware, sign-in completion and session scope.274- `references/theming.md`: the sub-themes, `useWindTheme`, the button and field standards, modal presentation.275- `references/backend-contract.md`: the `api/v1` endpoints each controller calls, the backend keys that must match, the refusal codes.