fai/chain-studio
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(studio): Welcome page Phase B — embedded doc reader (v0.38.0)

Browse source 
Second slice of the Welcome surface. Operator-facing
documentation now lives inside Studio as bundled assets and
renders inline via a modal sheet — no browser, no external
link, air-gap-tauglich.

- Four operator-readable explainers under `assets/docs/`,
  each with an EN + DE pair:
    architecture[_de].md  — Hub / Module / Flow + how they fit
    security[_de].md       — sandbox model, declared perms,
                              operator ceiling
    audit[_de].md          — hash-chained log, WORM-1 mechanics,
                              `fai admin verify-events`
    flows[_de].md          — flow YAML, templating reference,
                              extract→summarize example
  These are short (≈ 300-500 words each), operator-shaped
  prose. Not copies of the architecture docs in
  fai_platform/docs/architecture/ — those are
  contributor-dense.

- pubspec.yaml declares `assets/docs/` so the markdown ships
  inside the Studio binary. Air-gap deployments read them
  with no network access.

- New `_DocReaderSheet` modal: 85 %-of-viewport bottom sheet,
  drag handle + title bar with the doc icon and close button,
  scrollable Markdown body styled to match Studio chrome.
  Loads `assets/docs/<slug>_<locale>.md` first, falls back to
  the EN file. Locale comes from
  `Localizations.localeOf(context)`.

- `_DocsRow` on the Welcome page sits below the trust-posture
  deck. Two-column grid on ≥ 640 dp, single column below.
  Each card is icon + title + one-line blurb + chevron;
  click opens the reader sheet for that slug.

- 12 new ARB keys for the docs section (header, blurb, four
  card titles + blurbs, close button, error message).
- 4 new icons reused: `account_tree_outlined` (architecture),
  `shield_outlined` (security), `verified_outlined` (audit),
  `alt_route_outlined` (flows).

Implements Phase B of `docs/landing-page-design.md`. Phase C
(live getting-started checklist with persistent state) is the
last remaining slice.

Signed-off-by: flemming-it <stefan.a.flemming@googlemail.com>
This commit is contained in:
flemming-it 2026-05-09 00:24:31 +02:00
parent 3a7d0e74ad
commit 3b07d340d5
16 changed files with 1051 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

13
lib/l10n/app_de.arb
View file

@ -20,6 +20,19 @@
"welcomeTrustAuditBody": "Flow-Läufe, Installationen, Deinstallationen, Freigabe-Entscheidungen — alles wird in ein hash-verkettetes Audit-Log geschrieben. Die Diagnose-Seite verifiziert die Kette bei jedem Laden komplett.",
"welcomeTrustAirgapTitle": "Air-Gap-tauglich",
"welcomeTrustAirgapBody": "Der gesamte Hub steckt in einem einzigen Binary für Linux, macOS und Windows. Sobald ein Modul installiert ist, läuft der Flow, der es nutzt, ohne weiteren Netzwerkzugriff — ideal für regulierte Umgebungen.",
"welcomeDocsHeader": "DOKUMENTATION",
"welcomeDocsBody": "Operator-Erklärungen, inline gerendert. Kein Browser, kein externer Link — air-gap-tauglich.",
"welcomeDocArchitectureTitle": "Architektur in einem Absatz",
"welcomeDocArchitectureBlurb": "Hub, Modul, Flow — und wie die drei zusammenpassen.",
"welcomeDocSecurityTitle": "Sandbox-Modell",
"welcomeDocSecurityBlurb": "Was ein Modul deklariert, was der Operator deckelt, was der Hub durchsetzt.",
"welcomeDocAuditTitle": "Manipulationssicheres Audit-Log",
"welcomeDocAuditBlurb": "Wie die Hash-Kette funktioniert und warum WORM-1 für KRITIS reicht.",
"welcomeDocFlowsTitle": "Flow-Komposition",
"welcomeDocFlowsBlurb": "YAML-Grundlagen, Templating-Referenz, das Extract→Summarize-Beispiel.",
"welcomeDocClose": "Schließen",
"welcomeDocFailedToLoad": "Doku konnte nicht geladen werden: {error}",
"@welcomeDocFailedToLoad": { "placeholders": { "error": { "type": "String" } } },
"navDoctor": "Diagnose",
"navModules": "Module",
"navStore": "Store",

13
lib/l10n/app_en.arb
View file

@ -21,6 +21,19 @@
"welcomeTrustAuditBody": "Flow runs, install / uninstall actions, approval decisions — all of them write into a hash-chained audit log. The Doctor page verifies the chain end-to-end on every load.",
"welcomeTrustAirgapTitle": "Air-gap ready",
"welcomeTrustAirgapBody": "The whole hub fits in a single binary that runs on Linux, macOS and Windows. Once a module is installed, the flow it powers runs without further network access — perfect for regulated environments.",
"welcomeDocsHeader": "DOCUMENTATION",
"welcomeDocsBody": "Operator-facing explainers, rendered inline. No browser, no external link — air-gap-friendly.",
"welcomeDocArchitectureTitle": "Architecture in one paragraph",
"welcomeDocArchitectureBlurb": "Hub, Module, Flow — and how the three fit together.",
"welcomeDocSecurityTitle": "Sandbox model",
"welcomeDocSecurityBlurb": "What a module declares, what the operator caps, what the hub enforces.",
"welcomeDocAuditTitle": "Tamper-evident audit log",
"welcomeDocAuditBlurb": "How the hash chain works and why WORM-1 is enough for KRITIS.",
"welcomeDocFlowsTitle": "Flow composition",
"welcomeDocFlowsBlurb": "YAML basics, templating reference, the extract→summarize example.",
"welcomeDocClose": "Close",
"welcomeDocFailedToLoad": "Could not load documentation: {error}",
"@welcomeDocFailedToLoad": { "placeholders": { "error": { "type": "String" } } },
"navDoctor": "Doctor",
"navModules": "Modules",
"navStore": "Store",

72
lib/l10n/app_localizations.dart
View file

@ -206,6 +206,78 @@ abstract class AppLocalizations {
/// **'The whole hub fits in a single binary that runs on Linux, macOS and Windows. Once a module is installed, the flow it powers runs without further network access — perfect for regulated environments.'**
String get welcomeTrustAirgapBody;
/// No description provided for @welcomeDocsHeader.
///
/// In en, this message translates to:
/// **'DOCUMENTATION'**
String get welcomeDocsHeader;
/// No description provided for @welcomeDocsBody.
///
/// In en, this message translates to:
/// **'Operator-facing explainers, rendered inline. No browser, no external link — air-gap-friendly.'**
String get welcomeDocsBody;
/// No description provided for @welcomeDocArchitectureTitle.
///
/// In en, this message translates to:
/// **'Architecture in one paragraph'**
String get welcomeDocArchitectureTitle;
/// No description provided for @welcomeDocArchitectureBlurb.
///
/// In en, this message translates to:
/// **'Hub, Module, Flow — and how the three fit together.'**
String get welcomeDocArchitectureBlurb;
/// No description provided for @welcomeDocSecurityTitle.
///
/// In en, this message translates to:
/// **'Sandbox model'**
String get welcomeDocSecurityTitle;
/// No description provided for @welcomeDocSecurityBlurb.
///
/// In en, this message translates to:
/// **'What a module declares, what the operator caps, what the hub enforces.'**
String get welcomeDocSecurityBlurb;
/// No description provided for @welcomeDocAuditTitle.
///
/// In en, this message translates to:
/// **'Tamper-evident audit log'**
String get welcomeDocAuditTitle;
/// No description provided for @welcomeDocAuditBlurb.
///
/// In en, this message translates to:
/// **'How the hash chain works and why WORM-1 is enough for KRITIS.'**
String get welcomeDocAuditBlurb;
/// No description provided for @welcomeDocFlowsTitle.
///
/// In en, this message translates to:
/// **'Flow composition'**
String get welcomeDocFlowsTitle;
/// No description provided for @welcomeDocFlowsBlurb.
///
/// In en, this message translates to:
/// **'YAML basics, templating reference, the extract→summarize example.'**
String get welcomeDocFlowsBlurb;
/// No description provided for @welcomeDocClose.
///
/// In en, this message translates to:
/// **'Close'**
String get welcomeDocClose;
/// No description provided for @welcomeDocFailedToLoad.
///
/// In en, this message translates to:
/// **'Could not load documentation: {error}'**
String welcomeDocFailedToLoad(String error);
/// No description provided for @navDoctor.
///
/// In en, this message translates to:

43
lib/l10n/app_localizations_de.dart
View file

@ -69,6 +69,49 @@ class AppLocalizationsDe extends AppLocalizations {
String get welcomeTrustAirgapBody =>
'Der gesamte Hub steckt in einem einzigen Binary für Linux, macOS und Windows. Sobald ein Modul installiert ist, läuft der Flow, der es nutzt, ohne weiteren Netzwerkzugriff — ideal für regulierte Umgebungen.';
@override
String get welcomeDocsHeader => 'DOKUMENTATION';
@override
String get welcomeDocsBody =>
'Operator-Erklärungen, inline gerendert. Kein Browser, kein externer Link — air-gap-tauglich.';
@override
String get welcomeDocArchitectureTitle => 'Architektur in einem Absatz';
@override
String get welcomeDocArchitectureBlurb =>
'Hub, Modul, Flow — und wie die drei zusammenpassen.';
@override
String get welcomeDocSecurityTitle => 'Sandbox-Modell';
@override
String get welcomeDocSecurityBlurb =>
'Was ein Modul deklariert, was der Operator deckelt, was der Hub durchsetzt.';
@override
String get welcomeDocAuditTitle => 'Manipulationssicheres Audit-Log';
@override
String get welcomeDocAuditBlurb =>
'Wie die Hash-Kette funktioniert und warum WORM-1 für KRITIS reicht.';
@override
String get welcomeDocFlowsTitle => 'Flow-Komposition';
@override
String get welcomeDocFlowsBlurb =>
'YAML-Grundlagen, Templating-Referenz, das Extract→Summarize-Beispiel.';
@override
String get welcomeDocClose => 'Schließen';
@override
String welcomeDocFailedToLoad(String error) {
return 'Doku konnte nicht geladen werden: $error';
}
@override
String get navDoctor => 'Diagnose';

43
lib/l10n/app_localizations_en.dart
View file

@ -69,6 +69,49 @@ class AppLocalizationsEn extends AppLocalizations {
String get welcomeTrustAirgapBody =>
'The whole hub fits in a single binary that runs on Linux, macOS and Windows. Once a module is installed, the flow it powers runs without further network access — perfect for regulated environments.';
@override
String get welcomeDocsHeader => 'DOCUMENTATION';
@override
String get welcomeDocsBody =>
'Operator-facing explainers, rendered inline. No browser, no external link — air-gap-friendly.';
@override
String get welcomeDocArchitectureTitle => 'Architecture in one paragraph';
@override
String get welcomeDocArchitectureBlurb =>
'Hub, Module, Flow — and how the three fit together.';
@override
String get welcomeDocSecurityTitle => 'Sandbox model';
@override
String get welcomeDocSecurityBlurb =>
'What a module declares, what the operator caps, what the hub enforces.';
@override
String get welcomeDocAuditTitle => 'Tamper-evident audit log';
@override
String get welcomeDocAuditBlurb =>
'How the hash chain works and why WORM-1 is enough for KRITIS.';
@override
String get welcomeDocFlowsTitle => 'Flow composition';
@override
String get welcomeDocFlowsBlurb =>
'YAML basics, templating reference, the extract→summarize example.';
@override
String get welcomeDocClose => 'Close';
@override
String welcomeDocFailedToLoad(String error) {
return 'Could not load documentation: $error';
}
@override
String get navDoctor => 'Doctor';

2
lib/main.dart
View file

@ -26,7 +26,7 @@ import 'widgets/widgets.dart';
/// Studio's own build version. Bump on every UI commit so the
/// running app self-identifies — visible in the sidebar header
/// and quick-glance proof that you're seeing the current build.
const String kStudioVersion = '0.37.0';
const String kStudioVersion = '0.38.0';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();

299
lib/pages/welcome.dart
View file

@ -9,8 +9,12 @@
// getting-started checklist.
import 'package:flutter/material.dart';
import 'package:flutter/services.dart' show rootBundle;
import 'package:flutter_markdown/flutter_markdown.dart';
import '../data/system_actions.dart';
import '../l10n/app_localizations.dart';
import '../theme/theme.dart';
import '../theme/tokens.dart';
class WelcomePage extends StatelessWidget {
@ -48,6 +52,10 @@ class WelcomePage extends StatelessWidget {
_SectionLabel(textKey: _SectionLabelKey.trust),
SizedBox(height: FaiSpace.md),
_TrustPosture(),
SizedBox(height: FaiSpace.xxl),
_SectionLabel(textKey: _SectionLabelKey.docs),
SizedBox(height: FaiSpace.md),
_DocsRow(),
],
),
),
@ -128,7 +136,7 @@ class _Hero extends StatelessWidget {
}
}
enum _SectionLabelKey { pillars, trust }
enum _SectionLabelKey { pillars, trust, docs }
class _SectionLabel extends StatelessWidget {
final _SectionLabelKey textKey;
@ -141,6 +149,7 @@ class _SectionLabel extends StatelessWidget {
final text = switch (textKey) {
_SectionLabelKey.pillars => l.welcomePillarsHeader,
_SectionLabelKey.trust => l.welcomeTrustHeader,
_SectionLabelKey.docs => l.welcomeDocsHeader,
};
return Text(
text,
@ -349,3 +358,291 @@ class _TrustRow extends StatelessWidget {
);
}
}
/// Doc-card entries — each links to a bundled markdown file
/// under `assets/docs/`. The slug is the filename stem; the
/// loader picks `<slug>.md` or `<slug>_de.md` per locale.
class _DocEntry {
final String slug;
final IconData icon;
final String Function(AppLocalizations) title;
final String Function(AppLocalizations) blurb;
const _DocEntry({
required this.slug,
required this.icon,
required this.title,
required this.blurb,
});
}
final List<_DocEntry> _kDocs = <_DocEntry>[
_DocEntry(
slug: 'architecture',
icon: Icons.account_tree_outlined,
title: (l) => l.welcomeDocArchitectureTitle,
blurb: (l) => l.welcomeDocArchitectureBlurb,
),
_DocEntry(
slug: 'security',
icon: Icons.shield_outlined,
title: (l) => l.welcomeDocSecurityTitle,
blurb: (l) => l.welcomeDocSecurityBlurb,
),
_DocEntry(
slug: 'audit',
icon: Icons.verified_outlined,
title: (l) => l.welcomeDocAuditTitle,
blurb: (l) => l.welcomeDocAuditBlurb,
),
_DocEntry(
slug: 'flows',
icon: Icons.alt_route_outlined,
title: (l) => l.welcomeDocFlowsTitle,
blurb: (l) => l.welcomeDocFlowsBlurb,
),
];
/// Two-by-two doc grid on wide windows, single column on
/// narrow. Each card opens `_DocReaderSheet` for its slug.
class _DocsRow extends StatelessWidget {
const _DocsRow();
@override
Widget build(BuildContext context) {
final l = AppLocalizations.of(context)!;
return Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
l.welcomeDocsBody,
style: Theme.of(context).textTheme.bodySmall?.copyWith(
color: Theme.of(context).colorScheme.onSurfaceVariant,
),
),
const SizedBox(height: FaiSpace.md),
LayoutBuilder(
builder: (context, constraints) {
final twoCols = constraints.maxWidth >= 640;
final cardWidth =
twoCols ? (constraints.maxWidth - FaiSpace.md) / 2 : double.infinity;
return Wrap(
spacing: FaiSpace.md,
runSpacing: FaiSpace.md,
children: [
for (final d in _kDocs)
SizedBox(
width: cardWidth,
child: _DocCard(entry: d),
),
],
);
},
),
],
);
}
}
class _DocCard extends StatelessWidget {
final _DocEntry entry;
const _DocCard({required this.entry});
@override
Widget build(BuildContext context) {
final theme = Theme.of(context);
final l = AppLocalizations.of(context)!;
return Material(
color: theme.colorScheme.surfaceContainer,
borderRadius: BorderRadius.circular(FaiRadius.md),
child: InkWell(
onTap: () => _DocReaderSheet.show(context, entry),
borderRadius: BorderRadius.circular(FaiRadius.md),
child: Container(
padding: const EdgeInsets.all(FaiSpace.lg),
decoration: BoxDecoration(
borderRadius: BorderRadius.circular(FaiRadius.md),
border: Border.all(color: theme.colorScheme.outlineVariant),
),
child: Row(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Icon(entry.icon, size: 22, color: theme.colorScheme.primary),
const SizedBox(width: FaiSpace.lg),
Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
entry.title(l),
style: theme.textTheme.titleSmall?.copyWith(
fontWeight: FontWeight.w600,
),
),
const SizedBox(height: 4),
Text(
entry.blurb(l),
style: theme.textTheme.bodySmall?.copyWith(
color: theme.colorScheme.onSurfaceVariant,
height: 1.4,
),
),
],
),
),
Icon(
Icons.chevron_right,
size: 18,
color: theme.colorScheme.onSurfaceVariant,
),
],
),
),
),
);
}
}
/// Modal bottom-sheet that loads the markdown for a doc entry
/// from `assets/docs/<slug>[_de].md` and renders it inline via
/// flutter_markdown. No browser, no network — KRITIS-friendly.
class _DocReaderSheet extends StatefulWidget {
final _DocEntry entry;
const _DocReaderSheet({required this.entry});
static Future<void> show(BuildContext context, _DocEntry entry) {
return showModalBottomSheet<void>(
context: context,
isScrollControlled: true,
backgroundColor: Theme.of(context).colorScheme.surfaceContainer,
shape: const RoundedRectangleBorder(
borderRadius: BorderRadius.vertical(top: Radius.circular(FaiRadius.md)),
),
builder: (_) => _DocReaderSheet(entry: entry),
);
}
@override
State<_DocReaderSheet> createState() => _DocReaderSheetState();
}
class _DocReaderSheetState extends State<_DocReaderSheet> {
late final Future<String> _content;
@override
void initState() {
super.initState();
_content = _load();
}
Future<String> _load() async {
final locale = Localizations.localeOf(context).languageCode;
final localised = 'assets/docs/${widget.entry.slug}_$locale.md';
final fallback = 'assets/docs/${widget.entry.slug}.md';
try {
return await rootBundle.loadString(localised);
} catch (_) {
return rootBundle.loadString(fallback);
}
}
@override
Widget build(BuildContext context) {
final theme = Theme.of(context);
final l = AppLocalizations.of(context)!;
final maxHeight = MediaQuery.of(context).size.height * 0.85;
return ConstrainedBox(
constraints: BoxConstraints(maxHeight: maxHeight),
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
Padding(
padding: const EdgeInsets.symmetric(vertical: FaiSpace.sm),
child: Container(
width: 40,
height: 4,
decoration: BoxDecoration(
color: theme.colorScheme.outlineVariant,
borderRadius: BorderRadius.circular(2),
),
),
),
Padding(
padding: const EdgeInsets.fromLTRB(
FaiSpace.xxl,
FaiSpace.sm,
FaiSpace.lg,
FaiSpace.sm,
),
child: Row(
children: [
Icon(widget.entry.icon, size: 20, color: theme.colorScheme.primary),
const SizedBox(width: FaiSpace.sm),
Expanded(
child: Text(
widget.entry.title(l),
style: theme.textTheme.titleMedium?.copyWith(
fontWeight: FontWeight.w600,
),
),
),
IconButton(
icon: const Icon(Icons.close, size: 18),
visualDensity: VisualDensity.compact,
tooltip: l.welcomeDocClose,
onPressed: () => Navigator.pop(context),
),
],
),
),
const Divider(height: 1),
Flexible(
child: FutureBuilder<String>(
future: _content,
builder: (context, snap) {
if (snap.connectionState == ConnectionState.waiting) {
return const Padding(
padding: EdgeInsets.all(FaiSpace.xxl),
child: Center(child: CircularProgressIndicator()),
);
}
if (snap.hasError) {
return Padding(
padding: const EdgeInsets.all(FaiSpace.xxl),
child: Text(
l.welcomeDocFailedToLoad(snap.error.toString()),
style: theme.textTheme.bodyMedium?.copyWith(
color: theme.colorScheme.error,
),
),
);
}
return Markdown(
data: snap.data ?? '',
padding: const EdgeInsets.all(FaiSpace.xxl),
selectable: true,
onTapLink: (text, href, title) async {
if (href != null && href.isNotEmpty) {
await SystemActions.openInOs(href);
}
},
styleSheet: MarkdownStyleSheet.fromTheme(theme).copyWith(
p: theme.textTheme.bodyMedium?.copyWith(height: 1.5),
code: FaiTheme.mono(
size: 12,
color: theme.colorScheme.onSurface,
),
codeblockDecoration: BoxDecoration(
color: theme.colorScheme.surfaceContainerHigh,
borderRadius: BorderRadius.circular(FaiRadius.sm),
),
),
);
},
),
),
],
),
);
}
}