MagicStarterManager

Introduction#

The manager is the configuration hub where host apps register custom user models, team resolvers, navigation items, header builders, logout callbacks and view overrides. What a notification type looks like is not one of its seams: that lives on magic_notifications's own NotificationViewRegistry (see Notifications).

The manager lives at lib/src/magic_starter_manager.dart. MagicStarterServiceProvider binds it as a container singleton in its register phase.

Singleton Pattern#

The manager is bound into the Magic IoC container under the key 'magic_starter' by the service provider:

app.singleton('magic_starter', () => MagicStarterManager());

All access goes through the MagicStarter facade, which resolves the singleton from the container:

static MagicStarterManager get manager {
  if (Magic.bound('magic_starter')) {
    return Magic.make<MagicStarterManager>('magic_starter');
  }
  // Falls back to a shared default manager instead of throwing.
  return _fallbackManager ??= MagicStarterManager();
}

Unbound Fallback and Testing#

Every accessor on the MagicStarter facade delegates through manager, so any code that reads a theme (for example MSCard through MagicStarter.cardTheme) would fail when rendered without MagicStarterServiceProvider bound, in a standalone widget test or a preview catalogue entry.

MagicStarter.manager checks Magic.bound('magic_starter') first. When unbound it falls back to a shared, lazily created default MagicStarterManager(), whose sub-themes all hold const defaults, instead of throwing. The fallback also prints a one-time kDebugMode warning (MagicStarterManager not bound; using defaults. Call MagicStarter... to configure.), so a forgot-to-bind bug in a real app still surfaces during development. A manager bound in the container always wins over the fallback.

For tests that need a specific manager configuration (custom theme, team resolver, etc.), bind one explicitly with setUpMagicStarterForTests():

import 'package:magic_starter/magic_starter.dart';

setUp(() {
  MagicApp.reset();
  Magic.flush();
  setUpMagicStarterForTests(); // binds a default MagicStarterManager()
});

Pass a pre-configured instance to bind it instead:

setUpMagicStarterForTests(
  manager: MagicStarterManager()
    ..cardTheme = const MagicStarterCardTheme(surfaceClassName: 'bg-white'),
);

setUpMagicStarterForTests() is Magic.singleton('magic_starter', () => manager ?? MagicStarterManager()) in one call. A test that only relies on default theme values can skip binding altogether and use the fallback. In a test that exercises the fallback itself, call MagicStarter.resetFallbackManagerForTests() in setUp, because Magic.flush() does not clear it.

User Model Registration#

By default the manager creates MagicStarterAuthUser instances from API data. Host apps override this to use their own Authenticatable subclass:

MagicStarter.useUserModel((data) => User.fromMap(data));

Internally the manager stores a UserModelFactory, a function that takes Map<String, dynamic> and returns Authenticatable:

UserModelFactory userFactory = (data) => MagicStarterAuthUser.fromMap(data);

The factory is invoked via MagicStarter.createUser(data) whenever the plugin needs to hydrate a user model from an API response.

Team Resolver#

The team resolver bridges the plugin's team UI with app-specific team models through three callbacks:

MagicStarter.useTeamResolver(
  currentTeam: () => User.current.currentTeam?.toMagicStarterTeam(),
  allTeams: () => User.current.allTeams
      .map((t) => t.toMagicStarterTeam())
      .toList(),
  onSwitch: (id) => MagicStarter.switchTeam('$id'),
);

The callbacks are wrapped in MagicStarterTeamResolverConfig:

MagicStarter.switchTeam(teamId) asks the backend to switch and answers whether it accepted; on success it re-identifies the store rail as the paying subject, so a purchase after the switch is not attributed to the team that was left. A refused switch changes nothing. A failure of that re-identification is logged and does not turn the answer into false, because the switch already happened. MagicStarter.currentTeamId() answers the active team's id as a string, or null without a resolver or an active team.

Navigation Configuration#

Host apps register navigation items for the authenticated app layout (sidebar, bottom bar and profile dropdown):

MagicStarter.useNavigation(
  mainItems: [
    MagicStarterNavItem(
      icon: Icons.dashboard,
      labelKey: 'nav.dashboard',
      path: '/',
    ),
  ],
  systemItems: [
    MagicStarterNavItem(
      icon: Icons.people_outline,
      labelKey: 'nav.members',
      path: '/teams/members',
    ),
  ],
  bottomItems: [
    MagicStarterNavItem(
      icon: Icons.dashboard_outlined,
      labelKey: 'nav.dashboard',
      path: '/',
    ),
  ],
  profileMenuItems: [
    MagicStarterNavItem(
      icon: Icons.notifications_outlined,
      labelKey: 'nav.notifications',
      path: '/notifications',
    ),
  ],
);

The items are stored in MagicStarterNavigationConfig:

Each MagicStarterNavItem takes icon, labelKey and path, plus these optional fields:

Navigation Theme#

MagicStarterNavigationTheme overrides the default text-primary tokens used for active nav items, the brand/logo, bottom navigation and user avatar colours, without requiring any view override.

MagicStarter.useNavigationTheme(
  MagicStarterNavigationTheme(
    activeItemClassName:
        'active:text-amber-500 active:bg-amber-500/10 dark:active:text-amber-400 dark:active:bg-amber-400/10',
    brandClassName:
        'text-lg font-bold text-amber-500 dark:text-amber-400',
    brandBuilder: (context) => Image.asset('assets/logo.png', height: 28),
    bottomNavActiveClassName: 'active:text-amber-500 dark:active:text-amber-400',
    avatarClassName: 'bg-amber-500/10 dark:bg-amber-400/10',
    avatarTextClassName: 'text-sm font-bold text-amber-600 dark:text-amber-400',
    dropdownAvatarClassName: 'bg-gradient-to-tr from-amber-500 to-amber-300',
    dropdownAvatarTextClassName: 'text-sm font-bold text-white',
  ),
);

All fields are optional; an omitted field keeps its default.

Both avatars draw the account's photo when profile_photo_url carries one, the first letter of the account's name when it does not, and a person glyph when there is no name to take a letter from: before the session is known, or for an account that never set one.

The theme is stored on MagicStarterManager as navigationTheme and reset to defaults by manager.reset(). The active theme is read at widget build time, so useNavigationTheme() can be called at any point before the layout is first painted.

Modal Theme#

MagicStarterModalTheme overrides the default tokens used for every modal dialog: confirmation dialogs, password prompts and two-factor modals. Works the same way as NavigationTheme: register once, all modals pick up the tokens at build time.

MagicStarter.useModalTheme(
  MagicStarterModalTheme(
    containerClassName: 'rounded-2xl bg-white dark:bg-gray-900',
    titleClassName: 'text-lg font-semibold text-gray-900 dark:text-white',
    descriptionClassName: 'text-sm text-gray-500 dark:text-gray-400',
    primaryButtonClassName: 'bg-primary hover:bg-primary/90 text-white',
    dangerButtonClassName: 'bg-red-600 hover:bg-red-700 text-white',
    warningButtonClassName: 'bg-amber-500 hover:bg-amber-600 text-white',
    inputClassName: 'rounded-lg border border-gray-300 dark:border-gray-600',
    maxWidth: 480,
  ),
);

All fields are optional; an omitted field keeps its default.

Presentation#

presentation: MagicStarterModalPresentation.adaptive opens every modal the starter opens, and every MSBottomSheet.show, as a bottom sheet below dialogBreakpoint and as a centred MSDialog (at most maxWidth) from it: a phone gets the sheet, a desktop window the dialog, from one setting. The screen width is read when a modal opens, so one that is already open keeps its form through a resize; MSBottomSheet.show(dialogBreakpoint:) is ignored, and a breakpoint the Wind theme does not carry throws a StateError naming MagicStarterModalTheme.dialogBreakpoint. Overlay routes (RouteDefinition.overlay) follow too: the provider installs a resolver on magic's router (MagicRoute.useOverlayPresentation), an MSBottomSheet built in a dialog route draws the dialog shell, and under dialog or sheet an overlay route stays the sheet it has always been.

presentation: MagicStarterModalPresentation.sheet opens the starter's modals as the same bottom sheet MSBottomSheet draws, at every width (the plan upgrade prompt, which opens through magic's MagicFeedback.showCustomDialog, stays a dialog): MSDialog.show, MSConfirmDialog.show (and its MagicStarterConfirmDialog alias), MagicStarterPasswordConfirmDialog.show, MagicStarterStepUpDialog.show and MagicStarterTwoFactorModal.show. MSBottomSheet.show(dialogBreakpoint:) then ignores its breakpoint and stays a sheet.

MagicStarter.useModalTheme(
  MagicStarter.modalTheme.copyWith(
    presentation: MagicStarterModalPresentation.sheet,
  ),
);

• Return values do not change: true or false from a confirm, the proof map or null from the step up.
• A sheet is full width on a phone. On a wide screen Flutter's Material 3 default caps it at 640 px; maxWidth applies to the dialog only.
• The setting is read when a modal opens. An MSDialog widget draws the sheet panel when it is built inside a bottom sheet route, and its dialog shell otherwise, so a dialog a host opens with its own showDialog keeps the shell.
• useWindTheme() keeps a modal field set before it, presentation included. After it, set the field with MagicStarter.modalTheme.copyWith(...), since a fresh MagicStarterModalTheme puts the derived colours it omits back on their defaults. useTheme() resets the modal theme, so set it after that.

The theme is stored on MagicStarterManager as modalTheme and reset to defaults by manager.reset(). The active theme is read at widget build time, so useModalTheme() can be called at any point before a dialog is shown.

Sidebar Footer Builder#

Add a custom widget between the navigation items and the user menu in both the desktop sidebar and mobile drawer:

MagicStarter.useSidebarFooter((context) {
  return MyVersionBadge();
});

The builder receives the current BuildContext and should return any widget: a version badge, environment indicator, support link, etc.

When sidebarFooterBuilder is null (the default), no extra content is rendered between navigation and the user menu.

Header Builder#

Replace the default app layout header with a custom widget:

MagicStarter.useHeader((context, isDesktop) {
  return AppHeader(showMenuButton: !isDesktop);
});

The builder receives the current BuildContext and a bool isDesktop flag so the header can adapt between desktop sidebar and mobile drawer layouts.

When headerBuilder is null, the app layout renders its built-in header with the team selector, the notification bell and the user profile dropdown.

Logout Callback#

Override the default logout behaviour to add custom cleanup steps:

MagicStarter.useLogout(() async {
  await Notify.logoutPush();
  await SocialAuth.signOut();
  await Auth.logout();
  MagicRoute.to('/auth/login');
});

When set, the profile dropdown's logout item calls this callback instead of MagicStarterAuthController.instance.logout(). This is useful for apps that need to unregister push tokens, sign out of social providers, or perform other cleanup before navigating to the login screen.

Work that has to happen while the session token still works belongs in a before-logout hook, which runs ahead of both sign-out paths (the profile dropdown, ahead of a custom onLogout, and MagicStarterAuthController.logout(), ahead of Auth.logout()):

MagicStarter.beforeLogout(() => SocialAuth.signOut());

Hooks run in registration order, each isolated and bounded to five seconds (MagicStarterManager.beforeLogoutTimeout); one that throws or times out is logged and the next still runs, because a sign-out the user asked for has to happen whatever a hook's network does. The same hook is not added twice. MagicStarterServiceProvider registers its token-revoke hook in boot(), so a hook your own provider registers after that runs on a revoked token: list the provider whose hook needs the session token before MagicStarterServiceProvider in providers. A host with its own sign-out button calls MagicStarter.manager.runBeforeLogoutHooks() before its own Auth.logout(). A sign-out the app performs on its own, such as magic's AuthInterceptor after a failed token refresh, does not run them: the token is already dead. The provider registers two of its own, see Before-Logout Hooks.

Login Callback#

Run custom logic after a fresh sign-in:

MagicStarter.useLogin(() async {
  await Analytics.identify(Auth.user());
});

MagicStarterServiceProvider registers an internal listener on magic's AuthLogin event (dispatched at the end of BaseGuard.startSession) that calls this callback, unawaited, and logs rather than rethrows on failure. It fires for every fresh sign-in path this package ships (password, two-factor challenge, social, guest, and phone OTP) and deliberately not for a cold-boot restore of a stored session or a team switch: both go through Auth.restore(), which dispatches AuthRestored, and only once an API sync confirms the user (never offline, never on a failed sync, never without a userEndpoint configured); neither path ever dispatches AuthLogin.

When onLogin is null (the default), nothing runs.

Guest Claim Callback#

Run custom logic once a guest claim settles:

MagicStarter.useGuestClaimed((GuestClaimOutcome outcome) async {
  if (outcome == GuestClaimOutcome.claimed) await Library.refresh();
});

Also accepted as the onGuestClaimed argument of MagicStarter.bootstrap(). With the guest_auth feature on, the provider's AuthLogin and AuthRestored listeners claim a pending guest record for a non-guest user and call this callback with every outcome but none (claimed, refused, promoted), each of which marks the first sign-in to a real account after a guest session on this device. It runs unawaited and a failure is logged, not rethrown; a sign-in and a restore that share one claim call it once. See Guest Claim for the flow.

When onGuestClaimed is null (the default), nothing runs.

Locale Application#

MagicStarterServiceProvider also applies a signed-in user's saved locale attribute to the running app automatically, so a Turkish account does not land on an English shell until its next cold boot. Configured with magic_starter.localization.apply_user_locale (default true):

Map<String, dynamic> get magicStarterConfig => {
  'magic_starter': {
    'localization': {'apply_user_locale': false}, // opt out
    // ...
  },
};

A named static listener on Auth.stateNotifier, plus one immediate "once, now" read in boot() for the ordinary cold-boot case, reads Auth.user()?.get<String>('locale') and hands any non-empty value to MagicStarterManager.applyLocale(), the same method a profile save calls once it changed the language. applyLocale() holds a single pending target: whichever call reaches it first for a given locale wins, and a same-frame second call for the same target is a no-op, so a profile save (which itself calls Auth.restore() and so wakes this listener too) still issues exactly one Lang.setLocale() call however long the catalogue load takes.

When Auth.check() is false, the user carries no locale, or the toggle is off, nothing happens.

Unified Theme#

MagicStarterTheme wraps every sub-theme object into a single configuration. Host apps can set the entire visual identity in one call, then selectively override individual sub-themes afterward:

MagicStarter.useTheme(
  MagicStarterTheme(
    navigation: MagicStarterNavigationTheme(
      activeItemClassName: 'active:text-amber-500 active:bg-amber-500/10',
    ),
    form: MagicStarterFormTheme(
      inputClassName: 'rounded-xl border-2 border-zinc-700',
    ),
    card: MagicStarterCardTheme(
      surfaceClassName: 'bg-zinc-50 dark:bg-zinc-900',
    ),
  ),
);

// Override just one sub-theme after unified set
MagicStarter.useAuthTheme(
  MagicStarterAuthTheme(cardClassName: 'rounded-3xl bg-zinc-900 p-8'),
);

The unified theme supports copyWith() for partial overrides:

final customTheme = MagicStarter.theme.copyWith(
  form: MagicStarterFormTheme(inputClassName: 'rounded-xl'),
);
MagicStarter.useTheme(customTheme);

The manager maintains bidirectional sync: the theme getter constructs a MagicStarterTheme from the individual fields, while the theme setter distributes each sub-theme to its respective field, so useTheme() and the individual use*Theme() methods work together. Call the unified one first: a later use*Theme() replaces only its own sub-theme.

All sub-theme classes live in lib/src/configuration/magic_starter_theme.dart.

Form Theme#

MagicStarterFormTheme overrides the class names for form inputs, labels, placeholders, buttons, links, and checkboxes across all auth and profile forms.

MagicStarter.useFormTheme(
  MagicStarterFormTheme(
    inputClassName: 'w-full px-4 py-4 rounded-xl bg-zinc-900 border border-zinc-700 text-white',
    primaryButtonClassName: 'w-full bg-indigo-600 hover:bg-indigo-700 text-white font-semibold',
  ),
);

useFormTheme() assigns the whole struct, so every field you leave out goes back to its default, including the ones useWindTheme() derived. To change one string and keep the rest, copy the active theme. Every sub-theme has the same copyWith:

MagicStarter.useFormTheme(
  MagicStarter.formTheme.copyWith(inputClassName: 'w-full py-[11px] ...'),
);
MagicStarter.useModalTheme(
  MagicStarter.modalTheme.copyWith(inputClassName: 'w-full py-[11px] ...'),
);

Auth Theme#

MagicStarterAuthTheme overrides the class names for the auth form card, title, subtitle, error banner, social divider, and link styles on login/register/forgot/reset pages.

MagicStarter.useAuthTheme(
  MagicStarterAuthTheme(
    cardClassName: 'rounded-3xl bg-zinc-900 border border-zinc-700 p-8',
    titleClassName: 'text-3xl font-black text-white text-center',
  ),
);

Card Theme#

MagicStarterCardTheme overrides the class names for MSCard variant backgrounds, border radius, padding, and title styles.

MagicStarter.useCardTheme(
  MagicStarterCardTheme(
    surfaceClassName: 'bg-zinc-900 border border-zinc-700',
    borderRadius: 'rounded-xl',
  ),
);

Page Header Theme#

MagicStarterPageHeaderTheme overrides the class names for the MSPageHeader container, title, subtitle, action container and compact bar, plus two layout switches.

MagicStarter.usePageHeaderTheme(
  MagicStarterPageHeaderTheme(
    titleClassName: 'text-3xl font-black text-white',
  ),
);

inlineActions, and the one combination that overflows#

The header stacks below sm and lays out as a row above it. An app that wants a row at EVERY width, so a phone header keeps its action beside the title instead of dropping it under the subtitle, overrides containerClassName:

MagicStarter.usePageHeaderTheme(
  const MagicStarterPageHeaderTheme(
    containerClassName: 'w-full flex flex-row items-start justify-between gap-3 ...',
    // Required with the override above, and easy to miss.
    inlineActions: true,
  ),
);

Setting the container alone overflows. inlineActions does two things: it selects containerInlineClassName, and it gives the title row flex-1 min-w-0 instead of sm:flex-1. Without the second half the title column is flex-initial, a loose fit, so a long title takes its intrinsic width and runs past the actions rather than shrinking. line-clamp-2 on the title does not help, for the same reason truncate does not without a constrained box.

MSPageHeader.inlineActions is bool? and defaults to this field, so a single screen can still opt out with inlineActions: false. MSPageScaffold does not expose the argument, which is why the theme is the only reachable switch for a scaffold consumer.

Large title#

largeTitle: true makes every MSPageHeader a large title and every MSPageScaffold collapse it into a compact bar on scroll, the starter's own pages included. A widget argument still wins (size: on the header, largeTitle: on the scaffold).

MagicStarter.usePageHeaderTheme(
  const MagicStarterPageHeaderTheme(
    largeTitle: true,
    largeTitleClassName: 'text-4xl lg:text-3xl font-bold text-fg',
    compactBarClassName: 'px-2 bg-white/80 dark:bg-gray-900/80 border-b border-color-border',
    compactBarOpaqueClassName: 'px-2 bg-surface-container border-b border-color-border',
    compactTitleClassName: 'text-base font-semibold text-fg truncate',
    compactBarBlurSigma: 24,
  ),
);

The bar is glass: compactBarClassName should be translucent, and compactBarBlurSigma blurs what scrolls under it (0 adds no blur layer). Under high contrast (MediaQuery.highContrast, iOS Increase Contrast) it paints compactBarOpaqueClassName with no blur. A semantic alias carries no opacity step, so MagicStarterTheme.fromWind sets both fills to the opaque bg-surface-container; a host after glass passes its own translucent fill.

Host-owned page chrome#

manager.pageChrome is a MagicStarterPageChrome, a ChangeNotifier that lives as long as the manager (reset() clears it, it does not replace it). A host that draws the page title and back control in its own bar registers a predicate:

MagicStarter.useHostPageChrome((context) => MediaQuery.sizeOf(context).width < 768);

Wherever it answers true, MSPageHeader draws only its actions (right aligned, nothing at all without them, no heading role) and reports a MagicStarterPageChromeEntry (title, subtitle, backLabel, backFallback, value equality) keyed by its own state; MSPageScaffold then builds neither the large title nor the compact bar. The predicate gets a context inside the page and is asked again when its dependencies (the MediaQuery it reads) or the header's widget change. A header reports only while its ModalRoute is the current one: it withdraws when a route is pushed over it and the moment its own route is popped, before the exit transition ends, and reports again when the page above is popped. So current names the top page, and is null when that page has no MSPageHeader. A header under no route reports whenever the predicate answers true.

Every starter page follows it, the two magic_notifications screens included: the starter mounts the inbox and the preferences with a headerBuilder that draws their header as an MSPageHeader (lib/src/routes/notification_routes.dart), so the inbox reports its title and keeps its mark-all-as-read action, and the preferences report the settings hub as their backFallback.

The host's bar listens and goes back with the fallback the page reported:

ListenableBuilder(listenable: MagicStarter.pageChrome, builder: (context, _) {
  final MagicStarterPageChromeEntry? entry = MagicStarter.pageChrome.current;
  return TopBar(title: entry?.title, onBack: () => MagicRoute.back(fallback: entry?.backFallback));
});

Layout Theme#

MagicStarterLayoutTheme overrides wind_kit class names and dimensions for the app layout shell: sidebar, header, the content area and its background, drawer background, brand bar, and bottom navigation. It also carries the two breakpoints and the compact width that decide when the sidebar appears and when it renders as an icon rail.

MagicStarter.useLayoutTheme(
  MagicStarterLayoutTheme(
    sidebarWidth: 280,
    sidebarClassName: 'h-full flex flex-col bg-zinc-900 border-r border-zinc-700',
    contentBackgroundLightColor: 'zinc',
    contentBackgroundLightShade: 50,
  ),
);

Page Geometry#

pageContainerClassName is the wind_kit geometry every page in the app shares: the width cap, the horizontal edge margins, and the vertical rhythm. MSPageContainer reads it, and MSPageScaffold composes MSPageContainer, so every page in this package and every page in the host app resolve to the same numbers.

// In AppServiceProvider.boot()
MagicStarter.manager.pageContainerClassName =
    'max-w-6xl px-4 sm:px-5 lg:px-8 pt-6 sm:pt-8 pb-24';

The geometry belongs to the host, not to this package. Magic Starter's account pages render inside the host's own shell (see Layout Theme and the layout.app view key), so a width chosen here is a guess about someone else's layout. Set one geometry and every page, starter-owned or host-owned, lines up by construction.

Carry the whole geometry in the one string. A cap that agrees while the padding does not still reads as two different pages.

It defaults to MagicStarterManager.defaultPageContainerClassName (max-w-7xl px-4 lg:px-8 pt-6 sm:pt-8 pb-16), so an app that configures nothing still gets a complete, capped, edge-padded page.

Per-page tuning goes through MSPageContainer's className, which is appended after the shared geometry:

MSPageContainer(
  className: 'pb-0', // This page ends with its own footer bar.
  child: pageBody,
)

View Registry Integration#

The manager holds a private MagicStarterViewRegistry instance, exposed via the view getter:

final MagicStarterViewRegistry _viewRegistry = MagicStarterViewRegistry();

MagicStarterViewRegistry get view => _viewRegistry;

The facade provides a shortcut: MagicStarter.view delegates to manager.view. All view and layout registration, lookup, and building flows through this single registry instance.

Default Views#

registerDefaultViews() runs in the constructor and fills the registry with the package's views, layouts and modals. It registers a key only when it is absent, so an override registered earlier is never replaced. A view whose feature is off is not registered:

notifications.list and notifications.preferences are not among them. Both screens live on magic_notifications's own Notify.view, which registerMagicStarterNotificationRoutes() re-registers wrapped in this package's page geometry; see Notifications. The default layout and modal keys are in View Registry.

MagicStarter Facade#

MagicStarter is a static class (private constructor MagicStarter._()) that delegates every call to the manager singleton. It is the API host apps use:

The reset() method on the manager restores every property to its default, clears the view registry and registers the default views again. Tests call it in setUp() for isolation.

Related Documentation#

• Service Provider: binds the manager and registers the Gate abilities.
• View Registry: the string-keyed view factory the manager holds.
• Installation: MagicStarter.bootstrap() in the host's AppServiceProvider.
• Views and Layouts: the app shell the layout theme styles.
• Magic service container: singleton and factory bindings.