fix(docs): paint the landing tabs before hydration and clear hydration mismatches

docs/app/components/ComarkHtml.vue

@@ -2,8 +2,15 @@
 import { onMounted, ref, watch } from "vue";
 
 // A block that has only an HTML renderer (annotate, diff, quiz, comments), drawn on the server by docs/markdown.ts.
-// `block` is its tag, so a page's styles can tell a diff from a screenshot without looking inside.
-const props = defineProps<{ html: string; block?: string }>();
+// `block` is its tag, so a page's styles can tell a diff from a screenshot without looking inside. A block inside a
+// paragraph, such as a suggestion, is `inline` and draws in a `span`, since a `div` would end the paragraph.
+// `blockProps` holds the block's attributes, which the HTML already carries, so they don't land on the element.
+const props = defineProps<{
+  html: string;
+  block?: string;
+  blockProps?: Record<string, unknown>;
+  inline?: boolean;
+}>();
 const root = ref<HTMLElement>();
 
 // Scripts inserted by v-html are inert. Recreate them after mounting or replacing the HTML; the package runtimes
@@ -21,5 +28,6 @@ watch(() => props.html, runScripts, { flush: "post" });
 </script>
 
 <template>
-  <div ref="root" class="comark-html" :data-block="block" v-html="html" />
+  <span v-if="inline" ref="root" class="comark-html" :data-block="block" v-html="html" />
+  <div v-else ref="root" class="comark-html" :data-block="block" v-html="html" />
 </template>

docs/app/components/content/LandingHero.vue

@@ -20,10 +20,17 @@ const command = computed(() => {
   ];
   return `${add} ${packages.value}`;
 });
-// A raised pill on a muted track, as a segmented control.
+// A raised pill on a muted track, as a segmented control. The indicator renders only in the browser. Until then Nuxt
+// UI draws the active tab's pill behind its trigger, so that pill gets the same look. Tailwind finds classes by their
+// full text, so the variant is written out each time.
 const segmented = {
   indicator: "bg-default shadow-xs ring ring-default",
-  trigger: "data-[state=active]:text-highlighted!",
+  trigger: [
+    "data-[state=active]:text-highlighted!",
+    "in-[[data-slot=list]:not(:has([data-slot=indicator]))]:data-[state=active]:before:bg-default",
+    "in-[[data-slot=list]:not(:has([data-slot=indicator]))]:data-[state=active]:before:ring",
+    "in-[[data-slot=list]:not(:has([data-slot=indicator]))]:data-[state=active]:before:ring-default",
+  ].join(" "),
 };
 const copied = ref(false);
 let copiedTimer: ReturnType<typeof setTimeout> | undefined;

docs/pages/doctor/annotate/annotation-outside-screenshot.md

@@ -6,14 +6,14 @@ An `::annotation` marks a spot on the screenshot it sits in. Outside one, it has
 The duck without a name tag.
 ::
 
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 ::
 ```
 ::
 
 ::correct
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=20 y=30 w=15 h=10}
 The duck without a name tag.
 :::

docs/pages/doctor/annotate/box-as-fraction.md

@@ -2,7 +2,7 @@ The values are percentages, so `x=0.25` is a quarter of one percent of the image
 
 ::incorrect
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=0.2 y=0.3 w=0.15 h=0.1}
 The duck without a name tag.
 :::
@@ -12,7 +12,7 @@ The duck without a name tag.
 
 ::correct
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=20 y=30 w=15 h=10}
 The duck without a name tag.
 :::

docs/pages/doctor/annotate/box-outside-image.md

@@ -2,7 +2,7 @@ A box that runs past the right or bottom edge of the image is cut off there, and
 
 ::incorrect
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=90 y=30 w=20 h=10}
 The duck at the far bank.
 :::
@@ -12,7 +12,7 @@ The duck at the far bank.
 
 ::correct
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=80 y=30 w=20 h=10}
 The duck at the far bank.
 :::

docs/pages/doctor/annotate/compare-content.md

@@ -5,10 +5,10 @@ A `::compare` lays out its two screenshots and nothing else, so text or other bl
 ::compare
 The pond before and after the fence.
 
-:::screenshot{src="/pond-before.png" alt="The pond with no fence"}
+:::screenshot{src="/pond.svg" alt="The pond with no fence"}
 :::
 
-:::screenshot{src="/pond-after.png" alt="The pond with a fence"}
+:::screenshot{src="/pond-fence.svg" alt="The pond with a fence"}
 :::
 ::
 ```
@@ -19,10 +19,10 @@ The pond before and after the fence.
 The pond before and after the fence.
 
 ::compare
-:::screenshot{src="/pond-before.png" alt="The pond with no fence"}
+:::screenshot{src="/pond.svg" alt="The pond with no fence"}
 :::
 
-:::screenshot{src="/pond-after.png" alt="The pond with a fence"}
+:::screenshot{src="/pond-fence.svg" alt="The pond with a fence"}
 :::
 ::
 ```

docs/pages/doctor/annotate/compare-same-image.md

@@ -3,10 +3,10 @@ A compare whose two screenshots are the same image shows no change, which usuall
 ::incorrect
 ```md
 ::compare
-:::screenshot{src="/pond.png" alt="The pond with no fence"}
+:::screenshot{src="/pond.svg" alt="The pond with no fence"}
 :::
 
-:::screenshot{src="/pond.png" alt="The pond with a fence"}
+:::screenshot{src="/pond.svg" alt="The pond with a fence"}
 :::
 ::
 ```
@@ -15,10 +15,10 @@ A compare whose two screenshots are the same image shows no change, which usuall
 ::correct
 ```md
 ::compare
-:::screenshot{src="/pond-before.png" alt="The pond with no fence"}
+:::screenshot{src="/pond.svg" alt="The pond with no fence"}
 :::
 
-:::screenshot{src="/pond-after.png" alt="The pond with a fence"}
+:::screenshot{src="/pond-fence.svg" alt="The pond with a fence"}
 :::
 ::
 ```

docs/pages/doctor/annotate/compare-screenshot-count.md

@@ -3,7 +3,7 @@ A `::compare` shows a before and an after, so it takes exactly two screenshots.
 ::incorrect
 ```md
 ::compare
-:::screenshot{src="/pond-after.png" alt="The pond with a fence"}
+:::screenshot{src="/pond-fence.svg" alt="The pond with a fence"}
 :::
 ::
 ```
@@ -12,10 +12,10 @@ A `::compare` shows a before and an after, so it takes exactly two screenshots.
 ::correct
 ```md
 ::compare
-:::screenshot{src="/pond-before.png" alt="The pond with no fence"}
+:::screenshot{src="/pond.svg" alt="The pond with no fence"}
 :::
 
-:::screenshot{src="/pond-after.png" alt="The pond with a fence"}
+:::screenshot{src="/pond-fence.svg" alt="The pond with a fence"}
 :::
 ::
 ```

docs/pages/doctor/annotate/compare-viewport-mismatch.md

@@ -3,10 +3,10 @@ Screenshots captured at different sizes lay the page out differently, so what mo
 ::incorrect
 ```md
 ::compare
-:::screenshot{src="/pond-before.png" alt="The pond with no fence" viewport="1440x900"}
+:::screenshot{src="/pond.svg" alt="The pond with no fence" viewport="1440x900"}
 :::
 
-:::screenshot{src="/pond-after.png" alt="The pond with a fence" viewport="1280x800"}
+:::screenshot{src="/pond-fence.svg" alt="The pond with a fence" viewport="1280x800"}
 :::
 ::
 ```
@@ -15,10 +15,10 @@ Screenshots captured at different sizes lay the page out differently, so what mo
 ::correct
 ```md
 ::compare
-:::screenshot{src="/pond-before.png" alt="The pond with no fence" viewport="1440x900"}
+:::screenshot{src="/pond.svg" alt="The pond with no fence" viewport="1440x900"}
 :::
 
-:::screenshot{src="/pond-after.png" alt="The pond with a fence" viewport="1440x900"}
+:::screenshot{src="/pond-fence.svg" alt="The pond with a fence" viewport="1440x900"}
 :::
 ::
 ```

docs/pages/doctor/annotate/invalid-color.md

@@ -2,7 +2,7 @@ Each named color means one thing: `violet`, the default, points something out, `
 
 ::incorrect
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=20 y=30 w=15 h=10 color="orange"}
 The duck without a name tag.
 :::
@@ -12,7 +12,7 @@ The duck without a name tag.
 
 ::correct
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=20 y=30 w=15 h=10 color="amber"}
 The duck without a name tag.
 :::

docs/pages/doctor/annotate/invalid-href.md

@@ -2,14 +2,14 @@
 
 ::incorrect
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks" href="pond.example.com/map"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks" href="pond.example.com/map"}
 ::
 ```
 ::
 
 ::correct
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks" href="https://pond.example.com/map"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks" href="https://pond.example.com/map"}
 ::
 ```
 ::

docs/pages/doctor/annotate/invalid-mode.md

@@ -3,10 +3,10 @@
 ::incorrect
 ```md
 ::compare{mode="overlay"}
-:::screenshot{src="/pond-before.png" alt="The pond with no fence"}
+:::screenshot{src="/pond.svg" alt="The pond with no fence"}
 :::
 
-:::screenshot{src="/pond-after.png" alt="The pond with a fence"}
+:::screenshot{src="/pond-fence.svg" alt="The pond with a fence"}
 :::
 ::
 ```
@@ -15,10 +15,10 @@
 ::correct
 ```md
 ::compare{mode="slider"}
-:::screenshot{src="/pond-before.png" alt="The pond with no fence"}
+:::screenshot{src="/pond.svg" alt="The pond with no fence"}
 :::
 
-:::screenshot{src="/pond-after.png" alt="The pond with a fence"}
+:::screenshot{src="/pond-fence.svg" alt="The pond with a fence"}
 :::
 ::
 ```

docs/pages/doctor/annotate/invalid-position.md

@@ -2,7 +2,7 @@
 
 ::incorrect
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x="20%" y=30 w=15 h=10}
 The duck without a name tag.
 :::
@@ -12,7 +12,7 @@ The duck without a name tag.
 
 ::correct
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=20 y=30 w=15 h=10}
 The duck without a name tag.
 :::

docs/pages/doctor/annotate/invalid-side.md

@@ -2,7 +2,7 @@ A side note sits to the left of the image, to its right, above it, or below it,
 
 ::incorrect
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=20 y=30 w=15 h=10 side="under"}
 The duck without a name tag.
 :::
@@ -12,7 +12,7 @@ The duck without a name tag.
 
 ::correct
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=20 y=30 w=15 h=10 side="bottom"}
 The duck without a name tag.
 :::

docs/pages/doctor/annotate/invalid-viewport.md

@@ -2,14 +2,14 @@
 
 ::incorrect
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks" viewport="1440 by 900"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks" viewport="1440 by 900"}
 ::
 ```
 ::
 
 ::correct
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks" viewport="1440x900"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks" viewport="1440x900"}
 ::
 ```
 ::

docs/pages/doctor/annotate/invisible-mark.md

@@ -2,7 +2,7 @@
 
 ::incorrect
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=20 y=30 w=15 h=10 mark="none"}
 The duck without a name tag.
 :::
@@ -12,7 +12,7 @@ The duck without a name tag.
 
 ::correct
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=20 y=30 w=15 h=10 mark="none" side="left"}
 The duck without a name tag.
 :::

docs/pages/doctor/annotate/missing-alt.md

@@ -2,14 +2,14 @@
 
 ::incorrect
 ```md
-::screenshot{src="/pond.png"}
+::screenshot{src="/pond.svg"}
 ::
 ```
 ::
 
 ::correct
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 ::
 ```
 ::

docs/pages/doctor/annotate/missing-note.md

@@ -2,7 +2,7 @@ An annotation's content is its note. Without one, the mark has a number and noth
 
 ::incorrect
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=20 y=30 w=15 h=10}
 :::
 ::
@@ -11,7 +11,7 @@ An annotation's content is its note. Without one, the mark has a number and noth
 
 ::correct
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=20 y=30 w=15 h=10}
 The duck without a name tag.
 :::

docs/pages/doctor/annotate/missing-src.md

@@ -9,7 +9,7 @@ A `::screenshot` without `src` has no image, so its marks and notes point at not
 
 ::correct
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 ::
 ```
 ::

docs/pages/doctor/annotate/needs-side.md

@@ -2,7 +2,7 @@
 
 ::incorrect
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=20 y=30 w=15 h=10 mark="circle" at=60 to="27,35"}
 The duck without a name tag.
 :::
@@ -12,7 +12,7 @@ The duck without a name tag.
 
 ::correct
 ```md
-::screenshot{src="/pond.png" alt="The pond map with three ducks"}
+::screenshot{src="/pond.svg" alt="The pond map with three ducks"}
 :::annotation{x=20 y=30 w=15 h=10 mark="none" side="top" at=60 to="27,35"}
 The duck without a name tag.
 :::