From 63695a575911ac0ac19b261cc31f1fd3a42e04fb Mon Sep 17 00:00:00 2001
From: Leo Farias <leoafarias@gmail.com>
Date: Mon, 21 Sep 2026 13:31:33 -0400
Subject: [PATCH 1/5] ci: analyze in CI the way maintainers analyze locally

The workflow ran the Dart analyzer with `fatal-infos: false` and
`fatal-warnings: false`, before `pub get` and before code generation, so
a green run said less than `melos run analyze` does. It now runs
`melos run analyze:dart --no-select` after the build runner, which is
exactly the first half of the local command.

Records the two gaps this cannot close from here: DCM needs a runner
binary and a licence secret, and the playground's DCM baseline hides 630
findings. Both are measured and written down, with the order to tackle
them and a warning about `dcm fix`, which on this tree rewrote
dependency-injection call sites and broke one file.
---
 .github/workflows/test.yml          | 12 ++---
 docs/maintainers/analysis-parity.md | 69 +++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+), 5 deletions(-)
 create mode 100644 docs/maintainers/analysis-parity.md

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 16a54880..349e285b 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -42,11 +42,6 @@ jobs:
         with:
           melos-version: 7.8.1
 
-      - uses: invertase/github-action-dart-analyzer@v1
-        with:
-          fatal-infos: false
-          fatal-warnings: false
-
       - name: Install dependencies
         run: fvm flutter pub get
 
@@ -54,6 +49,13 @@ jobs:
         run: melos run build_runner:build --no-select
         timeout-minutes: 5
 
+      # Runs what maintainers run: `dart analyze --fatal-infos` over every
+      # package, after code generation so generated files exist. DCM is the
+      # other half of `melos run analyze` and is not run here yet; see
+      # docs/maintainers/analysis-parity.md.
+      - name: Analyze
+        run: melos run analyze:dart --no-select
+
       - name: Check Contract Schemas
         run: melos run contracts:check --no-select
 
diff --git a/docs/maintainers/analysis-parity.md b/docs/maintainers/analysis-parity.md
new file mode 100644
index 00000000..35b359e5
--- /dev/null
+++ b/docs/maintainers/analysis-parity.md
@@ -0,0 +1,69 @@
+# Static analysis: what runs where
+
+Maintainer notes, current as of 2026-09-21.
+
+## The commands
+
+| Command | What it runs |
+| --- | --- |
+| `melos run analyze` | `analyze:dart` then `analyze:dcm` |
+| `melos run analyze:dart` | `dart analyze --fatal-infos` in every package |
+| `melos run analyze:dcm` | `dcm analyze . --fatal-style --fatal-warnings` in every package that depends on `dart_code_metrics_presets` |
+| `melos run analyze:all` | the above plus `dcm check-unused-files` and `dcm check-unused-code` |
+
+Run `melos run <script> --no-select` in scripts and CI. Without the flag melos
+prompts for a package and a non-interactive runner hangs on that prompt.
+
+## What CI runs
+
+The Test workflow ran `invertase/github-action-dart-analyzer` with
+`fatal-infos: false` and `fatal-warnings: false`, before `pub get` and before
+code generation. That reported strictly less than the local command, on a tree
+whose generated files did not exist yet.
+
+It now runs `melos run analyze:dart --no-select` after code generation, which
+is exactly the first half of `melos run analyze`.
+
+## The gap that remains: DCM in CI
+
+`analyze:dcm` is not in CI. Running it needs the `dcm` binary on the runner
+(`CQLabs/setup-dcm`) and a licence key in repository secrets. Until that is
+configured, DCM findings are caught only on developer machines.
+
+Closing it is one job step and one secret; it is not done here because this
+change cannot verify a secret it cannot see.
+
+## The other gap: the playground's DCM baseline
+
+`packages/playground/dcm_baseline.json` (written 2026-07-15 with DCM 1.38.0)
+suppresses **630 findings** — 30 warnings and 600 style issues. `melos run
+analyze` is green because of it.
+
+Measured on 2026-09-21 by moving the baseline aside:
+
+| Finding | Count |
+| --- | --- |
+| Prefer dot shorthands (enum prefixes, class instantiations, class prefixes) | 272 |
+| Missing a blank line before `return` | 161 |
+| Member ordering (fields, constructors, private/public methods) | 92 |
+| Named arguments do not match declaration order | 33 |
+| Avoid inferrable type arguments | 18 |
+| Everything else, including 30 warning-level findings | 54 |
+
+`dcm fix` resolves 601 of the 630 automatically. **Do not run it unreviewed:**
+on this tree it also rewrote `Provider.of<DeckDocumentStore>(context)` to
+`Provider.of(context)` at dependency-injection call sites, and produced one
+file that no longer compiled (`genui_conversation_session.dart`, a
+"move declaration closer to use" fix leaving a `final` potentially unassigned).
+That sweep was tried during this work and reverted.
+
+The 29 findings `dcm fix` cannot fix include real ones worth reading: a field
+that is never disposed in `main.dart`, a loop that always exits after one
+iteration in `superdeck_a2ui_transport.dart`, a function that always returns
+null in `google_schema_adapter.dart`, and a missing `unknown` map entry in
+`error_classifier.dart`.
+
+**Recommended order when this is picked up:** fix the 29 by hand first, because
+they are the ones that can be defects; then run `dcm fix` package by package
+with the diff reviewed; then delete the baseline so the debt cannot grow back
+unnoticed.

From 25c101307f1b7eb31528b66b8e086b028a6a4562 Mon Sep 17 00:00:00 2001
From: Leo Farias <leoafarias@gmail.com>
Date: Mon, 21 Sep 2026 13:33:48 -0400
Subject: [PATCH 2/5] refactor(builder): give slide assembly one owner

The CLI build and the editor's preview codec held the same four calls in
the same order: split the Markdown, parse front matter into options, and
parse sections and comments. `assembleSlides` is now that function, and
both call it. Plugins stay a build concern and the editor's
`DeckFormatException` stays an editor concern.

Consolidating only after parity was proven is what the first-principles
report asked for; the evidence, and the method for the renderer question
it also left open, are written down in
docs/maintainers/renderer-and-assembly-evaluation.md, along with the work
the editor's removal retired.
---
 .../renderer-and-assembly-evaluation.md       | 84 +++++++++++++++++++
 .../builder/lib/src/build/deck_builder.dart   | 17 +---
 .../lib/src/parsers/slide_assembler.dart      | 28 +++++++
 packages/builder/lib/superdeck_builder.dart   |  1 +
 .../src/parsers/slide_assembler_test.dart     | 75 +++++++++++++++++
 .../data/mappers/deck_markdown_codec.dart     | 14 +---
 6 files changed, 192 insertions(+), 27 deletions(-)
 create mode 100644 docs/maintainers/renderer-and-assembly-evaluation.md
 create mode 100644 packages/builder/lib/src/parsers/slide_assembler.dart
 create mode 100644 packages/builder/test/src/parsers/slide_assembler_test.dart

diff --git a/docs/maintainers/renderer-and-assembly-evaluation.md b/docs/maintainers/renderer-and-assembly-evaluation.md
new file mode 100644
index 00000000..93cf2124
--- /dev/null
+++ b/docs/maintainers/renderer-and-assembly-evaluation.md
@@ -0,0 +1,84 @@
+# Deferred evaluations: shared assembly and the Markdown renderer
+
+Maintainer notes, 2026-09-21. These are the two items the first-principles
+report left open after the correctness work (report §4, "Recheck assumptions
+where the product has changed").
+
+## 1. Shared slide assembly — evaluated, consolidated
+
+**Question.** The CLI build and the editor's preview codec each assembled
+slides from `MarkdownParser`, `SlideOptions`, `SectionParser` and
+`CommentParser`. Extract one function, or leave them apart?
+
+**Evidence.** The two were not merely similar, they were the same four calls in
+the same order:
+
+| | `DeckBuilder._runBuild` | `DeckMarkdownCodec.decode` |
+| --- | --- | --- |
+| split | `MarkdownParser().parse(markdown)` | `const MarkdownParser().parse(markdown)` |
+| options | `SlideOptions.parse(raw.frontmatter)` | identical |
+| sections | `SectionParser().parse(raw.content)` | identical |
+| comments | `CommentParser().parse(raw.content)` | identical |
+| around it | applies build plugins | wraps failures in `DeckFormatException` |
+
+Empirically, the front-matter work already ran every recognition fixture
+through both paths and asserted the same slide count, keys and errors
+(`deck_markdown_codec_test.dart`, "front matter recognition parity"), and
+rebuilding `demo/slides.md` after that change produced a byte-identical
+`superdeck.json`.
+
+**Decision.** Parity is proven, so consolidate: `assembleSlides(String)` now
+lives in `packages/builder/lib/src/parsers/slide_assembler.dart` and both
+callers use it. The differences above stayed with their callers, which is
+where they belong — plugins are a build concern, and the editor's exception
+type is an editor concern.
+
+**Deliberately not done.** No pipeline framework, no shared "deck service", no
+move of filesystem work or build status. The report asked for one small pure
+function; that is what exists.
+
+## 2. The Markdown renderer — evaluated, kept
+
+**Question.** `flutter_markdown_plus` renders slide content. Keep, or replace?
+
+**Decision: keep.** Nothing in this delivery depends on changing it, and no
+evidence was produced that a replacement is better for SuperDeck's mix of
+content. The correctness contracts the report asked for are now protected
+around it, which is the condition the report set before reopening this.
+
+**What a replacement would have to prove**, if anyone reopens it — this is the
+method, not a result, because the comparison has not been run:
+
+1. Render the same corpus on both renderers: the demo deck, the three fixture
+   decks under `packages/builder/test/fixtures/real_decks/`, and the docs
+   examples. Cover lists, tables, code blocks with the repo's syntax
+   highlighter, images resolved through `AssetCacheStore`, links, blockquotes,
+   GitHub alerts, selection and semantics.
+2. Prove capture parity: thumbnails, `SlideCaptureReadiness` participation and
+   a PDF export of the same deck, not just an on-screen frame.
+3. Measure first-frame and rebuild cost per slide on macOS and web release
+   builds, on the same decks.
+4. Show a concrete defect or missing capability the current renderer cannot
+   address. A working prototype is not a reason on its own.
+
+**Related, already decided elsewhere.** Diagram rendering is not part of this
+question: `docs/maintainers/adr/0001-runtime-mermaid-rendering.md` covers it,
+and it is settled.
+
+## 3. Work retired rather than finished
+
+The file-backed editor was removed, and with it the reasons for several items
+the report and its remediation plan tracked. Recorded so they are not
+rediscovered as gaps:
+
+| Retired | Why it no longer applies |
+| --- | --- |
+| Auto-save completion invariant (F3) | Nothing auto-saves. A deck is written when the reader saves it, from the document in memory. |
+| Save-a-copy of an externally opened file | No file is opened from outside the SuperDeck folder. |
+| Crash-safe writes for external files | Same: the only writer is the deck library, which writes new files through a temporary sibling and a rename. |
+| External-edit conflict policy | Nothing watches a file, so nothing can conflict with an external edit. |
+| Per-deck asset eviction on rebind | A save writes a new deck; it never replaces one, so there is nothing to evict. |
+
+The autosave work still has value as evidence of the defect and the fix; it is
+preserved on `fix/playground-save-safety` and `feat/playground-deck-assets`,
+which are not part of the review stack.
diff --git a/packages/builder/lib/src/build/deck_builder.dart b/packages/builder/lib/src/build/deck_builder.dart
index 5f4b1b0c..59dc679b 100644
--- a/packages/builder/lib/src/build/deck_builder.dart
+++ b/packages/builder/lib/src/build/deck_builder.dart
@@ -3,9 +3,7 @@ import 'dart:async';
 import 'package:logging/logging.dart';
 import 'package:superdeck_core/superdeck_core.dart';
 
-import '../parsers/comment_parser.dart';
-import '../parsers/markdown_parser.dart';
-import '../parsers/section_parser.dart';
+import '../parsers/slide_assembler.dart';
 import 'build_event.dart';
 import 'deck_build_plugin.dart';
 
@@ -136,18 +134,7 @@ class DeckBuilder {
     await _beginBuildPlugins();
 
     final markdownRaw = await store.readDeckMarkdown();
-    final rawSlides = MarkdownParser().parse(markdownRaw);
-
-    final parsedSlides = [
-      for (final raw in rawSlides)
-        Slide(
-          key: raw.key,
-          options: SlideOptions.parse(raw.frontmatter),
-          sections: SectionParser().parse(raw.content),
-          comments: CommentParser().parse(raw.content),
-        ),
-    ];
-    final slides = await _applyBuildPlugins(parsedSlides);
+    final slides = await _applyBuildPlugins(assembleSlides(markdownRaw));
 
     await store.saveReferences(slides);
     await _finishBuildPlugins();
diff --git a/packages/builder/lib/src/parsers/slide_assembler.dart b/packages/builder/lib/src/parsers/slide_assembler.dart
new file mode 100644
index 00000000..64a422b7
--- /dev/null
+++ b/packages/builder/lib/src/parsers/slide_assembler.dart
@@ -0,0 +1,28 @@
+import 'package:superdeck_core/superdeck_core.dart';
+
+import 'comment_parser.dart';
+import 'markdown_parser.dart';
+import 'section_parser.dart';
+
+/// Builds slide models from deck Markdown.
+///
+/// This is the whole of stage 1 and 2 parsing: split the document into slides,
+/// read each slide's front matter into options, and parse its content into
+/// sections and comments. The CLI build and the editor's preview codec both
+/// call it, so a deck cannot parse one way on disk and another way on screen.
+///
+/// Callers add their own concerns around it: the build applies its plugins,
+/// and the editor wraps failures in a [DeckFormatException] it can show.
+///
+/// Throws [FormatException] for front matter that is recognized but invalid.
+List<Slide> assembleSlides(String markdown) {
+  return [
+    for (final raw in const MarkdownParser().parse(markdown))
+      Slide(
+        key: raw.key,
+        options: SlideOptions.parse(raw.frontmatter),
+        sections: const SectionParser().parse(raw.content),
+        comments: const CommentParser().parse(raw.content),
+      ),
+  ];
+}
diff --git a/packages/builder/lib/superdeck_builder.dart b/packages/builder/lib/superdeck_builder.dart
index 59afd9e2..21c4e7ee 100644
--- a/packages/builder/lib/superdeck_builder.dart
+++ b/packages/builder/lib/superdeck_builder.dart
@@ -10,5 +10,6 @@ export 'src/build/deck_builder.dart';
 
 export 'src/parsers/comment_parser.dart';
 export 'src/parsers/markdown_parser.dart';
+export 'src/parsers/slide_assembler.dart';
 export 'src/parsers/section_parser.dart';
 export 'src/parsers/slide_serializer.dart';
diff --git a/packages/builder/test/src/parsers/slide_assembler_test.dart b/packages/builder/test/src/parsers/slide_assembler_test.dart
new file mode 100644
index 00000000..fc4b4e33
--- /dev/null
+++ b/packages/builder/test/src/parsers/slide_assembler_test.dart
@@ -0,0 +1,75 @@
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:superdeck_builder/superdeck_builder.dart';
+import 'package:superdeck_core/superdeck_core.dart';
+import 'package:test/test.dart';
+
+/// The assembly the CLI build and the editor preview share.
+///
+/// The two used to hold identical copies of these four calls. These tests fix
+/// what the shared function produces, over the decks the repository actually
+/// ships, so a future change to one consumer cannot quietly change the other.
+void main() {
+  String canonical(List<Slide> slides) =>
+      jsonEncode([for (final slide in slides) slide.toJson()]);
+
+  group('assembleSlides', () {
+    test('reads front matter, sections and comments off one slide', () {
+      final slides = assembleSlides('''
+---
+title: Opening
+layout: fullscreen
+---
+
+# Hello
+
+<!-- a speaker note -->
+
+@section
+Body text
+''');
+
+      expect(slides, hasLength(1));
+      final slide = slides.single;
+      expect(slide.options?.title, 'Opening');
+      expect(slide.sections, isNotEmpty);
+      expect(slide.comments, contains('a speaker note'));
+    });
+
+    test('splits a deck the way the separators say', () {
+      final slides = assembleSlides('# One\n\n---\n\n# Two\n\n---\n\n# Three\n');
+
+      expect(slides, hasLength(3));
+      expect(slides.map((slide) => slide.key).toSet(), hasLength(3));
+    });
+
+    test('reports invalid recognized front matter', () {
+      expect(
+        () => assembleSlides('---\ntitle: "unclosed\n---\nBody\n'),
+        throwsFormatException,
+      );
+    });
+
+    test('assembles the demo deck', () {
+      final demo = File('../../demo/slides.md');
+      if (!demo.existsSync()) {
+        markTestSkipped('demo/slides.md not found');
+
+        return;
+      }
+
+      final slides = assembleSlides(demo.readAsStringSync());
+
+      expect(slides, hasLength(greaterThan(20)));
+      expect(
+        slides.every((slide) => slide.key.isNotEmpty),
+        isTrue,
+        reason: 'every slide is addressable',
+      );
+      // Assembling twice is the same deck: no counters, clocks or randomness.
+      expect(canonical(assembleSlides(demo.readAsStringSync())),
+          canonical(slides));
+    });
+  });
+}
diff --git a/packages/playground/lib/core/data/mappers/deck_markdown_codec.dart b/packages/playground/lib/core/data/mappers/deck_markdown_codec.dart
index fa2318aa..9ae82f54 100644
--- a/packages/playground/lib/core/data/mappers/deck_markdown_codec.dart
+++ b/packages/playground/lib/core/data/mappers/deck_markdown_codec.dart
@@ -5,20 +5,10 @@ import 'package:superdeck_core/superdeck_core.dart';
 class DeckMarkdownCodec {
   const DeckMarkdownCodec();
 
-  /// Parses [markdown] with the same pipeline used by the live preview loader.
+  /// Parses [markdown] with the same assembly the CLI build uses.
   List<Slide> decode(String markdown) {
     try {
-      final rawSlides = const MarkdownParser().parse(markdown);
-
-      return [
-        for (final raw in rawSlides)
-          Slide(
-            key: raw.key,
-            options: SlideOptions.parse(raw.frontmatter),
-            sections: const SectionParser().parse(raw.content),
-            comments: const CommentParser().parse(raw.content),
-          ),
-      ];
+      return assembleSlides(markdown);
     } catch (error, stackTrace) {
       Error.throwWithStackTrace(
         DeckFormatException(

From bc90981f1f41de2dd9b3b61afef7f9c0a3245cd8 Mon Sep 17 00:00:00 2001
From: Leo Farias <leoafarias@gmail.com>
Date: Mon, 21 Sep 2026 13:39:01 -0400
Subject: [PATCH 3/5] chore(playground): drop DCM baseline entries for deleted
 code
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Removing the editor left 187 suppressed findings across 21 files that no
longer exist, a third of the baseline. A stale entry cannot hide a
current finding, so deleting them changes no analysis result — `dcm
analyze` is still clean — and it stops the file from overstating the
debt. 468 suppressed findings remain, all naming live files.
---
 docs/maintainers/analysis-parity.md   |  12 +-
 packages/playground/dcm_baseline.json | 383 --------------------------
 2 files changed, 10 insertions(+), 385 deletions(-)

diff --git a/docs/maintainers/analysis-parity.md b/docs/maintainers/analysis-parity.md
index 35b359e5..71f58cf0 100644
--- a/docs/maintainers/analysis-parity.md
+++ b/docs/maintainers/analysis-parity.md
@@ -36,8 +36,16 @@ change cannot verify a secret it cannot see.
 ## The other gap: the playground's DCM baseline
 
 `packages/playground/dcm_baseline.json` (written 2026-07-15 with DCM 1.38.0)
-suppresses **630 findings** — 30 warnings and 600 style issues. `melos run
-analyze` is green because of it.
+suppresses findings that `melos run analyze` would otherwise fail on.
+
+Removing the editor emptied a third of it: 187 suppressed findings across 21
+files named code that no longer exists. Those entries were deleted — a stale
+entry cannot hide a current finding, so pruning them is safe and it stops the
+file from looking like more debt than it is. **468 suppressed findings remain**,
+all naming live files.
+
+Measured on 2026-09-21 by moving the baseline aside (630 findings at that
+point, before the prune, on the tree that still had the editor):
 
 Measured on 2026-09-21 by moving the baseline aside:
 
diff --git a/packages/playground/dcm_baseline.json b/packages/playground/dcm_baseline.json
index 24ba81b5..e2e13365 100644
--- a/packages/playground/dcm_baseline.json
+++ b/packages/playground/dcm_baseline.json
@@ -571,57 +571,6 @@
           "ff213c70e20583d4a8461e8a7fdc6769"
         ]
       },
-      "lib/features/ai/quick_agent/domain/commands/generate_deck_command.dart": {
-        "member-ordering": [
-          "93ac312546071a4932c9cb72821b311a"
-        ],
-        "prefer-shorthands-with-enums": [
-          "9d8cd4c8f6b2f7f01a366c97c50b2311",
-          "bbfc1d5b729389800243cd8eacf3d25a"
-        ],
-        "newline-before-return": [
-          "92bc3a2631bf7f0106dc346803864748"
-        ]
-      },
-      "lib/features/ai/quick_agent/presentation/pages/generation_lab_page.dart": {
-        "prefer-shorthands-with-enums": [
-          "9d8cd4c8f6b2f7f01a366c97c50b2311"
-        ],
-        "prefer-shorthands-with-constructors": [
-          "25d70aceeb5c316696c392bd922e2a3d",
-          "7619ac479ac9f2834cfe7d877347194d",
-          "946405a29e13e101d76b4f487157091b"
-        ],
-        "arguments-ordering": [
-          "a8a23a1abccd94a98763e6004de4bb5a",
-          "bcce95b8af165a092ef546e7a7732a36"
-        ]
-      },
-      "lib/features/ai/quick_agent/presentation/widgets/agent_generate_panel.dart": {
-        "avoid-inferrable-type-arguments": [
-          "3f63415e4669117ff49f73960a4719d0"
-        ],
-        "arguments-ordering": [
-          "6326f0a8f7d22bcf44408b4b40766394",
-          "8232e166fa8a8e0a94a441a6c3a01d42",
-          "96595505e89aeecacf57a685d06b08a0",
-          "094f9f454ebc330a63b3bff5cdc4609c",
-          "182748331b10a62fe44266e10eb6fd69"
-        ],
-        "member-ordering": [
-          "b5835f6e92a662adefd7198c41a57a4d"
-        ],
-        "avoid-flexible-outside-flex": [
-          "63f6baf1d88963b8c8210751c8530e94"
-        ],
-        "newline-before-return": [
-          "97f35e09dd652b8cc9c05af8f77d59df",
-          "22b210e70c24cf6aeb85ae1d1219afa6"
-        ],
-        "avoid-passing-async-when-sync-expected": [
-          "f5cdc7a986cf2cda9c809339d8f575fc"
-        ]
-      },
       "lib/features/ai/wizard/chat/view/widgets/chat_genui_panels.dart": {
         "prefer-shorthands-with-enums": [
           "09121fdc5a685f7523093cd7cbd10592"
@@ -965,338 +914,6 @@
           "86747cb1f8d1d1b6c1ba5fcd39c97fa9"
         ]
       },
-      "lib/features/editor/data/mac_os_deck_file_repository.dart": {
-        "member-ordering": [
-          "61583f66c352086f625389bc4ec09021",
-          "fe3c5f76041302ca56fa2b9a2d8e5bb8",
-          "f2a5b394cc08c2d1d3858687110b3e3c",
-          "e38bd19dad0e32b1de36b4c63785eaa5",
-          "bea9afc203854cfac0ea530e8a1f6e37",
-          "d4770d7dde3618d4fd6246f3e1b5cde6",
-          "b1f63da170cf8be0becbaecb6fd42204",
-          "c0571bb3bc54506aa599dde3bdb4ecae",
-          "9c1c1af7a5bd604dc9d8d3a17633814b",
-          "7c5d3f311125d65ce50413677b0848a0",
-          "a5325d91d264d106aa29c0dc85e040df",
-          "a094e3bb5adad62a7b32b85cb5c61f29",
-          "ee305b8ba526e1893318dc05bba5430e",
-          "30cc7c5b21586551726810d0cd4d43bc",
-          "8b23f0c3af08fa157c757de9878ef8ee",
-          "ac4269ef67ed74b93cda267b43206c69",
-          "02384a1078a73e8be254c95b3a249241",
-          "b7d338dba32395c4ff833a7e77d3505e",
-          "cac40f6301b09de3894205d9b2e4aad0",
-          "2ac1d9197942bd12e2c0f89839c0e59d",
-          "23e14a48452a1a533807727b01040c18",
-          "d9d85e9c7b2c389f6640a0cb95074a0a",
-          "a9ac5627806d7d2619a028a77b615677",
-          "dd8de04404a29aff3d0dd3cd441290dd"
-        ],
-        "newline-before-return": [
-          "91b07d2f59e53033238af396a151fdcc",
-          "5b13a5f22af000168fb43624f4c5e30d",
-          "7f0cab5db84d38ae4cf80b20c16985dd",
-          "aa7a7d5299fc46c3295977ab5b977f88",
-          "505b97969baa28c3f607a38ee02f4f2d",
-          "cca1137add70ca0139c19f0870da0d08",
-          "a3197ed059a2770f9613ee8d3f1853a0",
-          "c0c1fb2d771c5e23460368028f9c3ac5",
-          "580ea924302c212de4d376f6876e3127",
-          "d194a91f80ac759937b191156ba15dc7",
-          "8b7adf8726b22b17c204aeca8312e063",
-          "7d7e97fc617d1d6d2eb2dc89a49bdd6b"
-        ],
-        "avoid-unnecessary-local-late": [
-          "f2c67381db28fa11c59fe7a6df0f2587"
-        ],
-        "avoid-unused-assignment": [
-          "b3e1e9dcd03f9d3d459fd80e8cf33395"
-        ],
-        "avoid-throw-in-catch-block": [
-          "959b7175f88493905e3c324c2bf6f97d"
-        ],
-        "prefer-null-aware-elements": [
-          "57f7b0a0cdf14ad8caafe195cce8b6ef"
-        ],
-        "avoid-inferrable-type-arguments": [
-          "91fb37915e0b137471ffed358a98df47"
-        ]
-      },
-      "lib/features/editor/domain/files/deck_file.dart": {
-        "member-ordering": [
-          "e2d8f6a392cae18de2345a18e98b9dad",
-          "a4bf12cad1b7e45fa0b783b1d7d2b55c",
-          "1aa40d100698ed08fc6ff488d6c979ae",
-          "af74e680814898972d72f0d395f924e0",
-          "6b96878b5a62afdb18f1f10afe089726",
-          "8a471518a3589e64e269981b1ad4f3a5",
-          "7d63454bc73388949594a19405262cfb",
-          "ddb043095f98ae8064bc32218e627e79",
-          "be8c26dcc636a143b78001de86957301",
-          "a6ae710537c5749c910b8cc49a716d7a"
-        ]
-      },
-      "lib/features/editor/domain/stores/deck_document_store.dart": {
-        "member-ordering": [
-          "91ad2f066c7b26baefd76cd473e37991"
-        ]
-      },
-      "lib/features/editor/domain/stores/deck_file_session.dart": {
-        "member-ordering": [
-          "8922a3f0dcbbae6a4b1a02040a1ec1af",
-          "630f69deeef01d03ccf5d50ce70adbb7",
-          "8f384ac6d1e3a31809ad223d4133439a",
-          "be9361f9577f2afcea775b29f0acd0dc",
-          "241460c16dde8c69276eecac54904d5e",
-          "76b53ca63f31a7acab5d0eb87669ddbc",
-          "1af7570a71e03fba43cbda87c237afae",
-          "3696a97859b3657b6dbf7845208fdf2b",
-          "749dffe5db1373029f75dcb8732c56b6",
-          "9c90309785d2262d131e84dcee4fb54c"
-        ],
-        "prefer-shorthands-with-enums": [
-          "aa071c1154e0c2a1a966ae5e9ba4cdcb",
-          "d0f1730bd6a052818f96347b2602dff7"
-        ],
-        "avoid-explicit-pattern-field-name": [
-          "2063c1608d6e0baf80249c42e2be5804"
-        ],
-        "avoid-unnecessary-type-assertions": [
-          "02bf8d3cf8169dcdd6fbd16ba219f220"
-        ],
-        "newline-before-return": [
-          "cf7d3bedb9b566e7bf05fbe1d4f9b527",
-          "aa7a7d5299fc46c3295977ab5b977f88",
-          "505b97969baa28c3f607a38ee02f4f2d",
-          "13a19489a554a2f1393d0b243b42300c",
-          "2e913be2539392ddf88e8ee8b320b20e",
-          "d0fb1625c2453fc80769deb4b7780c87"
-        ],
-        "no-empty-block": [
-          "99914b932bd37a50b983c5e7c90ae93b"
-        ]
-      },
-      "lib/features/editor/presentation/pages/editor_bootstrap.dart": {
-        "newline-before-return": [
-          "46e4c2b3161e333714f1c17e4f194bbd"
-        ],
-        "prefer-shorthands-with-enums": [
-          "2fb447c7564c2415535ac785c401d9e9",
-          "09121fdc5a685f7523093cd7cbd10592",
-          "ca84476bcef57522ee2a8ab81af423b9"
-        ],
-        "arguments-ordering": [
-          "2e586805e1da05ba5cbbb014bd1d337e",
-          "1def888a6ccb4653203079fe4b44f4ca",
-          "0a5b69544522a5243a3d73d2ea34e4e4",
-          "808a1822c1e024c34f42bb156b1b3a0f"
-        ],
-        "avoid-inferrable-type-arguments": [
-          "bb9ba2fa6d63f9448496a5e277869998",
-          "9772b903b9ec7a48c0b1f7c812bc7819",
-          "bfd922d88a4d97c4357586a293d1996d",
-          "5f7efaf080b60420d599580ae6dc96b5",
-          "e696d9c4d2adf40459d446470223c647"
-        ],
-        "prefer-spacing": [
-          "1976d7f704de389d9fe064e08ea35b2d"
-        ],
-        "dispose-fields": [
-          "fbaeb96efaa627fe0086f3085ce7b208"
-        ]
-      },
-      "lib/features/editor/presentation/pages/editor_page.dart": {
-        "prefer-shorthands-with-static-fields": [
-          "6cccba5231bfbb08e0b2daef3de25229",
-          "4a3f84f00650af06d1e5833a82a463fe",
-          "415fa17381f186fe57ec7f1abbc608a0",
-          "c85833e43ec2eabb53e14a78c045ced4"
-        ],
-        "arguments-ordering": [
-          "4665a00097aa7b49046b0b115971348c",
-          "ace5a9b34f1b89caf9886445defbd06e",
-          "54c31391e9717ca0902f89f9c2b4adc1"
-        ],
-        "avoid-flexible-outside-flex": [
-          "63f6baf1d88963b8c8210751c8530e94"
-        ],
-        "prefer-shorthands-with-enums": [
-          "93a8349bb1ba0d0d7dd38cee75cda07c"
-        ]
-      },
-      "lib/features/editor/presentation/widgets/color_control.dart": {
-        "member-ordering": [
-          "f2ad75afca5f2dea07b66387fd09d7fa"
-        ],
-        "newline-before-return": [
-          "f32cefc2bc90e20f597987f052bab928"
-        ],
-        "arguments-ordering": [
-          "15162e31fd85e9f9f696fafa2d416a59"
-        ],
-        "prefer-shorthands-with-enums": [
-          "1a43318b6aa6d3969cd534097a9b35f8"
-        ],
-        "prefer-declaring-const-constructor": [
-          "ccbff554cea742890218ec2cc549d4c4"
-        ]
-      },
-      "lib/features/editor/presentation/widgets/committed_text_field.dart": {
-        "member-ordering": [
-          "5c5693934be35425e66e96c9e53205c6",
-          "9fdb867da7097a6856ee3f4033c35e57"
-        ],
-        "newline-before-return": [
-          "505b97969baa28c3f607a38ee02f4f2d"
-        ],
-        "arguments-ordering": [
-          "e993f6c13609c08e76e80682c5d4f4f5"
-        ]
-      },
-      "lib/features/editor/presentation/widgets/customization_sidebar.dart": {
-        "prefer-shorthands-with-constructors": [
-          "f02a8b91e92f721c96c4ab2efb4ec46c",
-          "7619ac479ac9f2834cfe7d877347194d"
-        ],
-        "avoid-flexible-outside-flex": [
-          "63f6baf1d88963b8c8210751c8530e94"
-        ],
-        "prefer-shorthands-with-enums": [
-          "cccb0164ac1854ef081278e0c9957698",
-          "65384f4b491613277bda0739ad40f805",
-          "a18fefb61010d739ff802caad056ae74",
-          "7bff7f612462dc538f921eb60f4692a7",
-          "37d2b4bb4d81f71166e9cddf21bdda52",
-          "713619fa3d96c97eff6b553bec280e0b",
-          "3beeab99d6eb30affa90fbf04b8f5e85",
-          "fe331f45f8c3eb9aafe615ff64e8ebdd"
-        ],
-        "avoid-inferrable-type-arguments": [
-          "3c3f6530e00e9f4ea603911863a90a6c",
-          "a4f5c9920c2235bcf03341de5d2e2d58",
-          "01b4d30c4566f2bce2f348c8ea97828c"
-        ],
-        "newline-before-return": [
-          "4e33c61e4293a9cfaa27322398f024f8",
-          "12daece9ad2d65c67b9702af7bb9de8d"
-        ],
-        "member-ordering": [
-          "3055d749cfc00745b52ce797d02dc5fb",
-          "09078a29d0fb566461b09a3d34277aba"
-        ],
-        "arguments-ordering": [
-          "007a61ca375e5264fbb7a12a82b5513d",
-          "de5ee6b2d67865cbc3b72ae112e22b77",
-          "9676eb77ec4fb21fce14d873c327b906",
-          "c21714beeb161f80eafb3413c9f0ba9a"
-        ]
-      },
-      "lib/features/editor/presentation/widgets/editor_controls.dart": {
-        "arguments-ordering": [
-          "9e056fab164a8e52503f23613b7c0dec",
-          "0e9a6bfeb18997f83290c99cd0506781"
-        ]
-      },
-      "lib/features/editor/presentation/widgets/editor_header.dart": {
-        "prefer-shorthands-with-static-fields": [
-          "c52645537c6ab5d7f975731fba0f51fb"
-        ],
-        "arguments-ordering": [
-          "40b32e296b138447fb6f36c185bb0cc2",
-          "97b9475b2474e6dc7fa85090243af89e"
-        ],
-        "avoid-passing-async-when-sync-expected": [
-          "5386071a6701c922773bb4d79fe6c8c2"
-        ]
-      },
-      "lib/features/editor/presentation/widgets/labels.dart": {
-        "avoid-nested-shorthands": [
-          "1b9f5562501632c961c2a1941df643fa"
-        ]
-      },
-      "lib/features/editor/presentation/widgets/new_deck_dialog.dart": {
-        "avoid-inferrable-type-arguments": [
-          "3f63415e4669117ff49f73960a4719d0"
-        ],
-        "arguments-ordering": [
-          "17c54337e65c3088f7be183597d79490",
-          "00169233536c07b4060c89351486d8e2",
-          "082cc69453174f90fd51edd2960a38b6"
-        ],
-        "member-ordering": [
-          "3c835028f65367a04fa7471b9eadbe57"
-        ],
-        "newline-before-return": [
-          "505b97969baa28c3f607a38ee02f4f2d"
-        ],
-        "avoid-explicit-pattern-field-name": [
-          "cb5e100e5a9a3e7f6d1fd97512215282"
-        ],
-        "prefer-shorthands-with-enums": [
-          "1a43318b6aa6d3969cd534097a9b35f8"
-        ],
-        "prefer-shorthands-with-static-fields": [
-          "c52645537c6ab5d7f975731fba0f51fb"
-        ],
-        "avoid-passing-async-when-sync-expected": [
-          "ded299993aecd79e8a394c6d7b6693dc"
-        ]
-      },
-      "lib/features/editor/presentation/widgets/preview_sidebar.dart": {
-        "avoid-flexible-outside-flex": [
-          "63f6baf1d88963b8c8210751c8530e94"
-        ],
-        "arguments-ordering": [
-          "821004b6f85223b79054e98e34d845e4"
-        ]
-      },
-      "lib/features/editor/presentation/widgets/text_editor.dart": {
-        "arguments-ordering": [
-          "8f8753de2732c69653d49c7410c46ed3",
-          "cfc526a459c22b011ae984f916d29e30",
-          "b18ed831f98b2838e62ea6dafd828681"
-        ],
-        "prefer-shorthands-with-static-fields": [
-          "4105ec7836e4cc697f33afa3b6b9b7c1",
-          "4c41a8c08da6df7cda65c40c9384cff8"
-        ],
-        "newline-before-return": [
-          "864a08bf2e563e78afb0cc3b038fe615"
-        ]
-      },
-      "lib/features/editor/utils/edit_reaction.dart": {
-        "prefer-returning-shorthands": [
-          "f9ed261a4a72bb61f69a6c97b43f4661"
-        ],
-        "member-ordering": [
-          "8950853c7250da9c19c8d63c67904b4c",
-          "5aa519f1defa2119b09590d8a019435a",
-          "a9bf9ebb2122599a489fcd6856bbc73e",
-          "f2168e94e8aad4a006773fe48465160f"
-        ],
-        "prefer-declaring-const-constructor": [
-          "31dcb21bc8dda167157618d29b14eee9"
-        ]
-      },
-      "lib/features/editor/utils/slide_navigation.dart": {
-        "newline-before-return": [
-          "fd3b4022619434ef02dd8bcdce80a954",
-          "6035c38641c02142fe249c287a985c86",
-          "bbef19786c08a56d47025fc80a748f53"
-        ]
-      },
-      "lib/features/editor/utils/text_editor_controller.dart": {
-        "prefer-shorthands-with-enums": [
-          "3c59534c2e89509c7cd82960f9a265b3"
-        ],
-        "newline-before-return": [
-          "e4a60cdf936c0d20dbc367d602943658"
-        ],
-        "dispose-class-fields": [
-          "1500740cd68882286797953d281dc599",
-          "07993c6c9c0086e4fe2dca83f59f70d7"
-        ]
-      },
       "lib/features/presentation/presentation/pages/presentation_page.dart": {
         "arguments-ordering": [
           "ae98919610014a68ef4167073420111c"

From 609cb1babf7f2132bab57408281f8ada828efdec Mon Sep 17 00:00:00 2001
From: Leo Farias <leoafarias@gmail.com>
Date: Mon, 21 Sep 2026 14:06:08 -0400
Subject: [PATCH 4/5] docs(maintainers): record the F1-F6 outcome and the
 platform blockers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

States for each finding whether it still applies and where it was fixed,
or that the editor's removal retired it and what replaced it, using the
report's own labels. Adds the §6 hardening answers, the measured Mermaid
web bundle delta in the ADR, and the two checks this environment cannot
run: no macOS app builds at all against the repo's 10.15 deployment
target on this Xcode, and Playwright's WebKit build does not install on
macOS 27. Raising the deployment target is left as an isolated decision.
---
 .../adr/0001-runtime-mermaid-rendering.md     | 23 ++++--
 docs/maintainers/first-principles-status.md   | 72 +++++++++++++++++++
 2 files changed, 90 insertions(+), 5 deletions(-)
 create mode 100644 docs/maintainers/first-principles-status.md

diff --git a/docs/maintainers/adr/0001-runtime-mermaid-rendering.md b/docs/maintainers/adr/0001-runtime-mermaid-rendering.md
index 9ae3f230..f235fc0a 100644
--- a/docs/maintainers/adr/0001-runtime-mermaid-rendering.md
+++ b/docs/maintainers/adr/0001-runtime-mermaid-rendering.md
@@ -303,8 +303,20 @@ Implemented on `feat/superdeck-mermaid-core`, not as a spike:
 - **No Node or mermaid.js in the product.** mermaid.js 12.0.0 was used once,
   locally, to record the reference behaviour in §4.2. The export-time
   JavaScript fallback (option 3) is closed for this delivery.
-- **No web payload measurement yet.** The release web bundle delta is still
-  unmeasured; see the blockers list in the delivery report.
+- **Web payload, measured.** Demo release web build, same machine and SDK,
+  before and after the swap:
+
+  | | before | after | delta |
+  | --- | --- | --- | --- |
+  | `main.dart.js` | 3.36 MB | 5.10 MB | **+1.74 MB** |
+  | `main.dart.js` gzipped | 1.01 MB | 1.63 MB | **+0.62 MB** |
+  | whole `build/web` | 47.7 MB | 49.5 MB | +1.7 MB |
+
+  The tree shaker cannot drop unused diagram families, because
+  `Mermaid.render()` switches over all 28 — as predicted in §4.5. At
+  **+0.62 MB compressed** this is inside the 1.5 MB exit criterion agreed
+  below, so the decision stands; it is the price of the restored families and
+  it is worth re-measuring on every `mermaid_core` bump.
 
 ## 7. Reconsideration triggers
 
@@ -337,8 +349,9 @@ Implemented on `feat/superdeck-mermaid-core`, not as a spike:
 
 ## 9. Still open
 
-- The release web bundle delta from retaining 28 diagram implementations is
-  unmeasured. Measure before the next web release; the exit threshold agreed
-  above was 1.5 MB compressed.
 - The vendored parser is a fork of one file. Re-check it on every
   `mermaid_core` bump, and delete it when upstream rejects both inputs.
+- Web payload is +0.62 MB compressed (§6). Inside the agreed threshold, but
+  re-measure on every bump; if a future release pushes it past 1.5 MB, the
+  options are deferred loading of the diagram code or dropping the dependency
+  for web only.
diff --git a/docs/maintainers/first-principles-status.md b/docs/maintainers/first-principles-status.md
new file mode 100644
index 00000000..c55731b5
--- /dev/null
+++ b/docs/maintainers/first-principles-status.md
@@ -0,0 +1,72 @@
+# First-principles report: what was done with each finding
+
+Source: the September 2026 first-principles review of `main` at `e719d66b`,
+findings F1–F6 and the hardening questions in its §6. Status as of 2026-09-21.
+
+Two of the six describe defects in a component that no longer exists. The
+playground's file-backed editor was removed in favour of the Wizard, which
+generates a deck, presents it, and writes it only when the reader asks. Those
+findings are recorded as retired, with what replaced them, rather than quietly
+dropped.
+
+## F1–F6
+
+| ID | The report's finding | Status | Where |
+| --- | --- | --- | --- |
+| **F1** | Saved Markdown does not retain generated image bytes across restart. | **Applicable — addressed** | A save writes `<name>.md`, `<name>.assets/` and `<name>.deck.json` together. Reopening in a fresh run with an empty memory cache resolves the artwork off disk. `deck_library_durability_test.dart` |
+| **F2** | Generation cleanup is not scoped to the saved deck that owns the artwork. | **Applicable — structurally prevented** | Nothing evicts artwork by key any more. Every save creates a new deck ("My talk", then "My talk 2"), so no save can touch an earlier deck's files. A→B→A ownership is asserted over a real filesystem. `deck_library_durability_test.dart`, `mac_os_deck_library_test.dart` |
+| **F3** | Undo during an active autosave can leave the latest document unsaved. | **Retired** | Nothing auto-saves. The deck is written from the in-memory document when the reader saves it. The fix and its regression tests remain on `fix/playground-save-safety`, which is not in the review stack. |
+| **F4** | A bullet-only slide can be consumed as frontmatter. | **Applicable — fixed** | `fix/front-matter-recognition`: a `- ` line is no longer YAML evidence on its own, and a recognized block that is not a YAML map is reported instead of silently emptied. |
+| **F5** | PDF capture does not wait for asynchronous content readiness. | **Applicable — fixed** | `fix/pdf-export-readiness`: one readiness scope per slide, a bounded wait, one more frame, and a failure that names the slide and the asset. Mermaid diagrams participate: a diagram that cannot render fails the wait. |
+| **F6** | Route-backed rendering and controller navigation can diverge after deck resizing. | **Applicable — fixed** | `fix/slide-route-authority`: the route is the single authority; `pageBuilder` no longer repairs state; mounted tests assert route, rendered slide, counter and actions together. |
+
+## The report's §6 hardening questions
+
+| Question | Status |
+| --- | --- |
+| **Crash-safe saving** | Addressed for the only writer left. The deck library writes Markdown, artwork and manifest each through a temporary sibling and a rename, and a failed save removes only what that save created. |
+| **External-edit conflicts** | **Retired.** Nothing watches a file, and no file outside the SuperDeck folder is opened, so there is no conflict to have a policy about. |
+| **Theme persistence** | Addressed. `<name>.deck.json` carries the theme's catalog id, version and density; reopening resolves it through the catalog and restores it. A selection the catalog no longer offers is reported rather than silently replaced. |
+| **Platform support and CI** | Partly. CI now runs the same Dart analysis maintainers run. DCM in CI and the macOS native checks are blocked; see `analysis-parity.md` and "Platform evidence" below. |
+| **Resource limits and PDF scope** | Open. Unchanged by this work: the PDF controller still holds every captured image in memory, and raster output is still the only format. |
+| **AI release model and security** | Open. Unchanged: compile-time key injection, image generation on for debug and opt-in for release. |
+
+## Platform evidence
+
+**What ran here:** package tests on the pinned SDK (macOS host), the
+deterministic generation checkpoint, and the browser smoke suite on Chromium.
+
+**What could not run, and why — not "not run", but blocked:**
+
+- **Any macOS app build.** `packages/playground/macos` and `demo/macos` pin
+  `MACOSX_DEPLOYMENT_TARGET = 10.15` (`Podfile`: `platform :osx, '10.15'`)
+  while the Xcode on this machine supports 12.0–27.0. Every macOS target fails
+  the same way:
+
+  > The macOS deployment target 'MACOSX_DEPLOYMENT_TARGET' is set to 10.15,
+  > but the range of supported deployment target versions is 12.0 to 27.0.x.
+
+  This blocks `melos run test:integration:macos` and any manual run of the
+  Wizard, so the **sandbox and security-scoped bookmark behaviour of saving
+  and reopening is unproven**. Everything below that layer is proven: the deck
+  library tests write, list, reopen and resolve artwork on the real macOS
+  filesystem, faking only the picker and bookmark calls, which cannot run
+  headless anyway.
+
+  Raising the deployment target is a supported-OS decision, deliberately left
+  as an isolated follow-up rather than changed inside this work.
+
+- **WebKit browser smoke.** `npx playwright install webkit` downloads
+  `webkit-mac-15-arm64` (Playwright 1.51's build for macOS 15) and fails to
+  install on this macOS 27.0 arm64 host. Chromium runs and passes; WebKit
+  needs either a newer Playwright whose WebKit build supports this OS, or a
+  CI runner on a supported macOS version.
+
+- **Known intermittent check.** `the address bar follows the active slide`
+  failed once in four Chromium runs at this head (and once before, on the
+  previous stack, with identical routing code). When it fails, the browser URL
+  never leaves `/?enable-flutter-web-semantics=true` even though the deck
+  advanced, which points at Flutter web's route reporting not being installed
+  yet at the moment of the first navigation, rather than at SuperDeck's route
+  authority. It is not caused by the Mermaid change, and the test was left
+  strict. Worth a deliberate wait-for-first-report in the harness.

From d3cbb8d9a659305c811ff42066a0c9c51f43abc6 Mon Sep 17 00:00:00 2001
From: Leo Farias <leoafarias@gmail.com>
Date: Mon, 21 Sep 2026 16:43:31 -0400
Subject: [PATCH 5/5] docs(maintainers): align cleanup terminology

---
 docs/maintainers/analysis-parity.md                         | 6 ++----
 docs/maintainers/renderer-and-assembly-evaluation.md        | 6 +++---
 packages/builder/lib/src/parsers/slide_assembler.dart       | 4 ++--
 packages/builder/test/src/parsers/slide_assembler_test.dart | 2 +-
 4 files changed, 8 insertions(+), 10 deletions(-)

diff --git a/docs/maintainers/analysis-parity.md b/docs/maintainers/analysis-parity.md
index 71f58cf0..369fd8cc 100644
--- a/docs/maintainers/analysis-parity.md
+++ b/docs/maintainers/analysis-parity.md
@@ -44,10 +44,8 @@ entry cannot hide a current finding, so pruning them is safe and it stops the
 file from looking like more debt than it is. **468 suppressed findings remain**,
 all naming live files.
 
-Measured on 2026-09-21 by moving the baseline aside (630 findings at that
-point, before the prune, on the tree that still had the editor):
-
-Measured on 2026-09-21 by moving the baseline aside:
+Measured on 2026-09-21 by moving the baseline aside (630 findings before the
+prune, on the tree that still had the editor):
 
 | Finding | Count |
 | --- | --- |
diff --git a/docs/maintainers/renderer-and-assembly-evaluation.md b/docs/maintainers/renderer-and-assembly-evaluation.md
index 93cf2124..873da553 100644
--- a/docs/maintainers/renderer-and-assembly-evaluation.md
+++ b/docs/maintainers/renderer-and-assembly-evaluation.md
@@ -6,7 +6,7 @@ where the product has changed").
 
 ## 1. Shared slide assembly — evaluated, consolidated
 
-**Question.** The CLI build and the editor's preview codec each assembled
+**Question.** The CLI build and the playground's deck codec each assembled
 slides from `MarkdownParser`, `SlideOptions`, `SectionParser` and
 `CommentParser`. Extract one function, or leave them apart?
 
@@ -30,8 +30,8 @@ rebuilding `demo/slides.md` after that change produced a byte-identical
 **Decision.** Parity is proven, so consolidate: `assembleSlides(String)` now
 lives in `packages/builder/lib/src/parsers/slide_assembler.dart` and both
 callers use it. The differences above stayed with their callers, which is
-where they belong — plugins are a build concern, and the editor's exception
-type is an editor concern.
+where they belong — plugins are a build concern, and the playground's
+`DeckFormatException` is an application-facing concern.
 
 **Deliberately not done.** No pipeline framework, no shared "deck service", no
 move of filesystem work or build status. The report asked for one small pure
diff --git a/packages/builder/lib/src/parsers/slide_assembler.dart b/packages/builder/lib/src/parsers/slide_assembler.dart
index 64a422b7..f121e9f4 100644
--- a/packages/builder/lib/src/parsers/slide_assembler.dart
+++ b/packages/builder/lib/src/parsers/slide_assembler.dart
@@ -8,11 +8,11 @@ import 'section_parser.dart';
 ///
 /// This is the whole of stage 1 and 2 parsing: split the document into slides,
 /// read each slide's front matter into options, and parse its content into
-/// sections and comments. The CLI build and the editor's preview codec both
+/// sections and comments. The CLI build and the playground's deck codec both
 /// call it, so a deck cannot parse one way on disk and another way on screen.
 ///
 /// Callers add their own concerns around it: the build applies its plugins,
-/// and the editor wraps failures in a [DeckFormatException] it can show.
+/// and the playground wraps failures in a [DeckFormatException] it can show.
 ///
 /// Throws [FormatException] for front matter that is recognized but invalid.
 List<Slide> assembleSlides(String markdown) {
diff --git a/packages/builder/test/src/parsers/slide_assembler_test.dart b/packages/builder/test/src/parsers/slide_assembler_test.dart
index fc4b4e33..cde6abd1 100644
--- a/packages/builder/test/src/parsers/slide_assembler_test.dart
+++ b/packages/builder/test/src/parsers/slide_assembler_test.dart
@@ -5,7 +5,7 @@ import 'package:superdeck_builder/superdeck_builder.dart';
 import 'package:superdeck_core/superdeck_core.dart';
 import 'package:test/test.dart';
 
-/// The assembly the CLI build and the editor preview share.
+/// The assembly the CLI build and the playground deck codec share.
 ///
 /// The two used to hold identical copies of these four calls. These tests fix
 /// what the shared function produces, over the decks the repository actually