Sdk koder kit

koder_kit

  • *rea:*Developer Platform
  • *ath:*engines/sdk/koder_kit
  • *ind:*Flutter SDK — base package for all Koder Flutter apps

Role in the stack

  • *ersion:*0.39.3

engines/sdk/koder_kit is the foundational Flutter package that every Koder app depends on. Wrapping the app root with KoderApp(config: ..., home: ...) or KoderApp.router(config: ..., routerConfig: ...) automatically injects the full set of behaviors mandated by specs/koder-app/behaviors.kmd:

  • *heme*— Material 3 light/dark using Koder design tokens; KoderThemeToggle widget
  • *uth*— Full OIDC authorizationcode + PKCE browser flow (KoderAuth.signIn()); SSO via KoderIPC; token storage and autorefresh
  • *uth UI*— KoderSignInButton, KoderUserBadge, KoderAuthGate for sign-in/out flows
  • *rror boundary*— catches unhandled Flutter errors, renders a userfriendly screen with a unique error ID (`PRODUCTCATCODESEQ) and "Ver detalhes" toggle; KoderErrorBanner` widget
  • *pdate checker*— queries Koder Hub on startup (cached 24h); blocks usage on mandatory updates
  • *elemetry*— batched structured logs and error events sent to the Koder observability stack
  • *afe area*— KoderSafeScaffold and KoderApp(safeArea: true) per specs/app-layout/safe-area.kmd
  • *ack behavior*— KoderBackScope per specs/navigation/back-behavior.kmd
  • *otion*— KdsMotion static tokens (5 durations, 4 easing curves, 6 spring descriptions, reduced-motion helpers) per specs/themes/motion/; widgets adopt via KdsMotion.durationMedium / KdsMotion.easeDecelerate / KdsMotion.reduced(ctx, d) instead of hardcoded Duration(...) / Curves.X
  • *I widgets*— 41widget koder_kit/ai.dart namespace (KAiChat, KAiBrowserView, KAiCheckpointTimeline, KAiFollowUps, KAiModelSelector, KAiPauseControls, KAiPlanReview, KAiPreview, KAiPublish, KAiRating, KAiScheduleList, KAiShareDialog, KAiSkillCardCreatorLibrary, KAiWorkspaceTree, KAiParallelTabs, KoderAIBubble, KoderAIDisclaimer, KoderAICodeBlock, KoderArtifactPanel, KoderCitationList, KoderComposer, KoderConversationList, KoderCostBadge, KoderGhostTextField, KoderMCPElicitationDialogPermissionSheetSamplingDialogServerChipServerDrawer/ToolCard, KoderMemoryPanel, KoderModelPicker, KoderPromptGallery, KoderStreamingText, KoderSystemPromptEditor, KoderThinkingBlock, KoderVoiceModeSheet, KoderAgentStepTrace) per umbrella KIT030 (closed 20260519, full T-suite coverage)

No wiring required: any app that uses KoderApp as its root gets all behaviors automatically.

Primary couplings

Module Relationship
foundation/id Auth: OIDC authorize + token + userinfo endpoints at id.koder.dev
dev/store Updates: hub.koder.dev/api/v1/apps/{slug}/latest
observe/log Telemetry: api.koder.dev/api/v1/logs batch endpoint
engines/sdk/koder_ipc IPC: bundled as dependency — KoderApp auto-registers the IPC server on startup
Every Koder Flutter app Consumer — KoderApp is the required root widget

Public API

// Minimal usage
KoderApp(
  config: KoderConfig(
    slug: 'dek',
    version: '1.0.0',
    ipcCapabilities: ['play', 'pause', 'stop'],
  ),
  home: const MyHomePage(),
)

// Auth — full OIDC browser flow
await auth.signIn();                   // SSO via IPC first, then browser PKCE
final user = auth.user;                // KoderUser after sign-in
final token = await auth.getValidToken(); // auto-refreshed

// Auth UI widgets
KoderSignInButton(onPressed: () => auth.signIn())
KoderUserBadge(user: auth.user!, onSignOut: () => auth.signOut())
KoderAuthGate(
  auth: auth,
  signedOut: (ctx) => KoderSignInButton(onPressed: () => auth.signIn()),
  signedIn: (ctx, user) => HomeScreen(user: user),
)

// Theme toggle
KoderThemeToggle()   // renders the light/dark toggle per spec

// Error banner
KoderErrorBanner(error: someError)

Interfaces

Export Kind Description
KoderApp Widget Root widget — injects all behaviors
KoderConfig Class App-level config (slug, version, base URLs)
KoderAuth ChangeNotifier OIDC PKCE + ROPC flows, token storage, autorefresh, user info, IPC SSO, OIDC end_session, isLoading ValueListenable, configurable storage prefix (KoderConfig.storagePrefix + legacyStoragePrefix migration). Full feature parity with flutter_appauthbased stacks (#026 + #027 shipped 20260508)
parseKoderUserFromIdToken top-level fn Local JWTclaims parse (subemailnamepreferred_usernamepicture); seeds userNotifier immediately without /userinfo roundtrip
KoderAuthCallbackHandler Class Multiplatform OAuth redirect delivery: AppLinks subscription on Android/iOS, 127.0.0.1:<callbackLoopbackPort> loopback HTTP server on desktop, Uri.base read on web. Autowired by KoderApp; nonOAuth URIs surfaced via KoderApp.onDeepLink. Eliminates need for flutter_appauth (#028)
KoderUser Class User profile from /userinfo (id, email, name, picture)
KoderSignInButton Widget Spec-compliant "Sign in with Koder ID" button
KoderUserBadge Widget Avatar + display name + sign-out popup
KoderAuthGate Widget Reactive signedin / signedout switcher
KoderThemeToggle Widget Lightdark toggle per `specsthemes/light-dark.kmd`
KoderErrorBoundary Widget Error screen with ID + "Ver detalhes"
KoderErrorBanner Widget Inline error banner for non-fatal errors
KoderSafeScaffold Widget Windowinsetsaware scaffold
KoderBackScope Widget Backbutton behavior per `specsnavigationbackbehavior.kmd`
KoderScaffold Widget Koder-branded scaffold with app bar + KoderThemeToggle
KoderUpdater Class Update check against Koder Hub
KoderUpdateBanner Widget Non-mandatory update hint banner (listens to KoderUpdate.notifier)
KoderUpdate Abstract class Static ValueNotifier<UpdateInfo?> for update state
KoderTelemetry Class Structured logging and error events
KoderTrack Abstract class Static helpers: tap(), page(), event() — fan to KoderTelemetry
KoderL10n Abstract class Static multilocale string loader with enUS fallback
koderTheme Function Returns ThemeData for light or dark
KoderColors Abstract class Koder design token color constants
generateErrorId Function Generates PRODUCT-CAT-CODE-SEQ IDs

OIDC browser flow (v0.6.0+)

KoderApp automatically subscribes to deep links on bootstrap via app_links. Redirect URIs per platform:

Platform Redirect URI
Android / iOS dev.koder.<slug>://auth
Desktop (LinuxmacOSWindows) http://127.0.0.1:18787/auth
Web ${idBaseUrl}/callback

Host apps must declare the URL scheme in AndroidManifest.xml / Info.plist. The desktop loopback port is handled transparently by app_links.

The IPC auth_token method is exposed automatically on every KoderApp so peer Koder apps can reuse the session without prompting the user again (per koder-app/behaviors.kmd §1.3).

Specs

  • specs/koder-app/behaviors.kmd — normative list of what every Koder app must implement
  • specs/errors/user-facing-messages.kmd — error screen format and ID structure
  • specs/themes/light-dark.kmd — theme requirements
  • specs/themes/motion.kmd — Motion index over the 3 sub-specs below
  • specs/themes/motion/easing-duration.kmd — R1 5 durations + R2 5 easing curves (consumed by KdsMotion.duration* / easeX)
  • specs/themes/motion/physics.kmd — R1 reduced-motion contract + R4 spring tokens (consumed by KdsMotion.springSpatial* / springEffect* and KdsMotion.reduced(...) helper)
  • specs/themes/motion/transitions.kmd — R1 transition pattern catalog + R3 page-level transitions
  • specs/app-layout/safe-area.kmd — safe area / window insets
  • specs/navigation/back-behavior.kmd — back button behavior

Status

embeds/ — 20260520. *ll six § Escopo widgets of #001 shipping live on kds.koder.dev* theme-toggle, sign-in-button, l10n-switcher, ui-style-picker, command-palette, title-bar. Each mounts only its widget in a thin _EmbedRoot and renders via <koder-embed widget="<slug>"> on the matching detail page. Built via make embeds in tools/design-gen/ (pattern rule embed-%); runtime canvaskit fetched from gstatic.com (Flutter --web-resources-cdn default), keeping each perwidget compressed bundle ≈0.69 MB (cap 2.5 MB). `titlebar ships visual fidelity only — drag/double-tap have no iframe equivalent so the embed shows the chrome with a one-line caption explaining the gap; spec doc remains the source of truth for desktop semantics. Adding a widget = clone embedsseed, write lib/main.dart, append slug to EMBED_WIDGETS in Makefile, flip EmbedShipped: true`.

v0.39.3 — 20260519. KdsMotion adoption — KAiChat._scrollToBottom now uses KdsMotion.durationMedium + KdsMotion.easeDecelerate + reduced-motion gate (jumpTo when MediaQuery.disableAnimations). First production adopter of the motion module shipped in 0.39.2.

v0.39.2 — 20260519. *dsMotion module*— canonical motion tokens per specs/themes/motion/. 5 Duration constants, 4 Cubic easing curves, 6 SpringDescription (3 spatial + 3 effect) with stiffnessdamping computed from spring dampingRatio per spec. Reducedmotion helpers: KdsMotion.respectsReducedMotion(ctx), KdsMotion.reduced(ctx, d), KdsMotion.reducedSpring(ctx, s). Wave 3 of the motion programme — Flutterside counterpart to the CSS tokens emitted by `toolsdesigngen at kds.koder.dev`. Mirror policy: when CSS tokens evolve (spec changes / Wave 2C buildtime generation), bump the matching Dart constants in tandem.

v0.39.1 — 20260519. Tsuites for the 23 KAi widgets shipped 20260519 (umbrella KIT030). Smoke render + 1-2 behavior tests each; full suite 427/427 passes.

v0.39.0 — 20260519. KAI suite umbrella KIT030 closed (12 carved subtickets + 5 pre-existing widgets). 23 widgets total in koder_kit/ai.dart namespace.

v0.7.0 — 20260423. Spec encapsulation batch: KoderScaffold (branded scaffold + theme toggle), KoderTrack (static tappageevent telemetry), KoderUpdateBanner + KoderUpdate.notifier (nonmandatory update UI), KoderL10n (multilocale string loader), KoderConfig.productName + displayName (auto window title). KoderApp wires all new helpers on bootstrap.

v0.6.0 — 20260423. Full OIDC authorization-code + PKCE browser flow shipped. KoderUser moved to auth.dart; auth UI widgets (KoderSignInButton, KoderUserBadge, KoderAuthGate) added in v0.5.0. KoderSafeScaffold in v0.3.0. KoderBackScope in v0.4.0.

Source: ../home/koder/dev/koder/meta/docs/stack/modules/sdk-koder-kit.md