@lernapps/app-templates 0.1.0 → 0.2.0

package/runtime/quiz/e2e.ts

@@ -1,9 +1,14 @@
-// The end-to-end tests of every quiz (@lernapps/app-templates/quiz/e2e), run by `lernapps check --pre-push` on the built
-// app with the app's own question bank. An app's e2e/quiz.e2e.ts is
+// The end-to-end tests of the quiz (@lernapps/app-templates/quiz/e2e), run by `lernapps check --pre-push` on the built
+// app with its own question bank, in two parts. quizTests() tests the app's content, and every app runs it: its
+// e2e/quiz.e2e.ts, part of the scaffold, is
 //
 //   import { quizTests } from "@lernapps/app-templates/quiz/e2e";
 //   quizTests();
 //
+// Each question's link opens it with its text and what it shows, its images loaded; without JavaScript every question
+// and its solution can be read; each other language has its page, its switch, and what a question shows there.
+// quizRuntimeTests() tests the runtime, the same in every app; only this repo runs it, on the template and its
+// fixtures (quiz/e2e/runtime.e2e.ts, not in the scaffold). What follows is what the two parts check together.
 // For each question: its deep link opens it, the right answer counts and a wrong one does not; after either, the
 // background of every option, the explanation and the links for further reading show, the learner's choice marked.
 // The feedback then has the focus and its top is in view, and the button to the next question comes after it.
@@ -37,8 +42,29 @@ const de = QUIZ_MESSAGES.de;
 /** The quiz's own texts in `lang`. */
 const messagesOf = messagesIn;
 
-/** The quiz's tests, for the question bank in `bank` (relative to the app's root). */
+/**
+ * The tests of a quiz's content, for the question bank in `bank` (relative to the app's root): what every app runs
+ * (e2e/quiz.e2e.ts). Each question's link opens it with what it shows; without JavaScript every question and its
+ * solution can be read; each other language has its page. What the runtime does the same in every app is
+ * quizRuntimeTests.
+ */
 export function quizTests(bank = "src/quiz.json"): void {
+  quizSuite(bank, "content");
+}
+
+/**
+ * The tests of the quiz's runtime on the question bank in `bank`: the right answer counts and a wrong one does not, with
+ * the feedback in view; the seed and the order; a run through every question to the full score; how many questions
+ * the learner chooses; what is stored. The template folder and the fixtures of lernapps/app-templates run them
+ * (e2e/runtime.e2e.ts); an app does not, its scaffold has no such file: they test the runtime, which is the same in
+ * every app, and their time grows with the bank (lernapps/app-templates#125).
+ */
+export function quizRuntimeTests(bank = "src/quiz.json"): void {
+  quizSuite(bank, "runtime");
+}
+
+function quizSuite(bank: string, part: "content" | "runtime"): void {
+  const content = part === "content";
   const all = JSON.parse(readFileSync(bank, "utf8")) as Quiz<Text>;
   const languages = quizLanguages(all);
   const quiz = quizIn(all, "de");
@@ -48,94 +74,115 @@ export function quizTests(bank = "src/quiz.json"): void {
     // answer: with motion, every click would wait for a scroll to settle, the run through a quiz grow with its size.
     test.use({ reducedMotion: "reduce" });
 
-    for (const item of quiz.questions) {
-      test(`${item.id} (${item.type}): its link opens it and the right answer counts`, async ({ page }) => {
-        await page.goto(`./#${questionId(item)}`);
-        await expect(question(page, item)).toBeVisible();
-        await expect(page.locator(".question:visible")).toHaveCount(1);
-        await answerQuestion(page, item, rightAnswer(item));
-        await expect(question(page, item).locator(".question-feedback")).toContainText(de.right);
-        await expectFeedbackInView(page, item);
-        // from the feedback, the keyboard reaches the next question (past the links of the background)
-        const next = question(page, item).locator(".question-next");
-        for (let tab = 0; tab < 30 && !(await next.evaluate((button) => button === document.activeElement)); tab++) {
-          await page.keyboard.press("Tab");
-        }
-        await expect(next).toBeFocused();
-        const reveal = question(page, item).locator(".question-reveal");
-        await expectBackground(reveal, item);
-        if (item.type === "single-choice" || item.type === "multiple-choice") {
-          const right = item.options.filter((option) => option.correct).length;
-          await expect(reveal.locator(".question-badge-right")).toHaveCount(right);
-          await expect(reveal.locator(".question-badge-right").first()).toHaveText(de.rightOption);
-        } else {
-          await expect(reveal).toContainText(de.rightAnswer);
-        }
+    if (content) {
+      for (const item of quiz.questions) {
+        test(`${item.id} (${item.type}): its link opens it, with what it shows`, async ({ page }) => {
+          await page.goto(`./#${questionId(item)}`);
+          await expect(question(page, item)).toBeVisible();
+          await expect(page.locator(".question:visible")).toHaveCount(1);
+          await expect(question(page, item).locator("legend")).toHaveText(item.text);
+          if (item.material !== undefined) await expectMaterial(page, item);
+        });
+      }
+
+      test.describe("without JavaScript", () => {
+        test.use({ javaScriptEnabled: false });
+
+        test("every question and its solution can be read", async ({ page }) => {
+          await page.goto("./");
+          for (const item of quiz.questions) {
+            await expect(question(page, item).locator("legend")).toHaveText(item.text);
+            await expectMaterial(page, item, { loaded: false });
+            await expectBackground(page.locator(`#loesung-${item.id}`), item);
+          }
+        });
       });
+    }
+
+    if (!content)
+      for (const item of quiz.questions) {
+        test(`${item.id} (${item.type}): its link opens it and the right answer counts`, async ({ page }) => {
+          await page.goto(`./#${questionId(item)}`);
+          await expect(question(page, item)).toBeVisible();
+          await expect(page.locator(".question:visible")).toHaveCount(1);
+          await answerQuestion(page, item, rightAnswer(item));
+          await expect(question(page, item).locator(".question-feedback")).toContainText(de.right);
+          await expectFeedbackInView(page, item);
+          // from the feedback, the keyboard reaches the next question (past the links of the background)
+          const next = question(page, item).locator(".question-next");
+          for (let tab = 0; tab < 30 && !(await next.evaluate((button) => button === document.activeElement)); tab++) {
+            await page.keyboard.press("Tab");
+          }
+          await expect(next).toBeFocused();
+          const reveal = question(page, item).locator(".question-reveal");
+          await expectBackground(reveal, item);
+          if (item.type === "single-choice" || item.type === "multiple-choice") {
+            const right = item.options.filter((option) => option.correct).length;
+            await expect(reveal.locator(".question-badge-right")).toHaveCount(right);
+            await expect(reveal.locator(".question-badge-right").first()).toHaveText(de.rightOption);
+          } else {
+            await expect(reveal).toContainText(de.rightAnswer);
+          }
+        });
 
-      if (item.material !== undefined) {
-        test(`${item.id} (${item.type}): what it shows is there, and its images load`, async ({ page }) => {
+        test(`${item.id} (${item.type}): a wrong answer does not count`, async ({ page }) => {
           await page.goto(`./#${questionId(item)}`);
-          await expectMaterial(page, item);
+          await answerQuestion(page, item, wrongAnswer(item));
+          await expect(question(page, item).locator(".question-feedback")).toContainText(de.wrong);
+          await expectFeedbackInView(page, item);
+          await expectBackground(question(page, item).locator(".question-reveal"), item);
+          if (item.type === "single-choice" || item.type === "multiple-choice") {
+            await expect(question(page, item).locator(".question-badge-chosen").first()).toHaveText(de.yourChoice);
+          }
         });
       }
 
-      test(`${item.id} (${item.type}): a wrong answer does not count`, async ({ page }) => {
-        await page.goto(`./#${questionId(item)}`);
-        await answerQuestion(page, item, wrongAnswer(item));
-        await expect(question(page, item).locator(".question-feedback")).toContainText(de.wrong);
-        await expectFeedbackInView(page, item);
-        await expectBackground(question(page, item).locator(".question-reveal"), item);
-        if (item.type === "single-choice" || item.type === "multiple-choice") {
-          await expect(question(page, item).locator(".question-badge-chosen").first()).toHaveText(de.yourChoice);
+    if (!content)
+      test("the seed in the address gives the order; without one, the address gets one", async ({ page }) => {
+        const everything = `&n=${quiz.questions.length}`;
+        const order = async (address: string) => {
+          await page.goto(address);
+          return page.locator(".question").evaluateAll((items) => items.map((item) => item.id).join());
+        };
+        const first = await order(`./?seed=11${everything}`);
+        expect(await order(`./?seed=11${everything}`)).toBe(first);
+        if (quiz.questions.length > 2) {
+          const others = [];
+          for (const seed of [12, 13, 14, 15, 16]) others.push(await order(`./?seed=${seed}${everything}`));
+          expect(others.some((other) => other !== first)).toBe(true);
         }
+        await page.goto("./");
+        await expect.poll(() => new URL(page.url()).searchParams.get("seed")).toMatch(/^\d+$/);
       });
-    }
 
-    test("the seed in the address gives the order; without one, the address gets one", async ({ page }) => {
-      const everything = `&n=${quiz.questions.length}`;
-      const order = async (address: string) => {
-        await page.goto(address);
-        return page.locator(".question").evaluateAll((items) => items.map((item) => item.id).join());
-      };
-      const first = await order(`./?seed=11${everything}`);
-      expect(await order(`./?seed=11${everything}`)).toBe(first);
-      if (quiz.questions.length > 2) {
-        const others = [];
-        for (const seed of [12, 13, 14, 15, 16]) others.push(await order(`./?seed=${seed}${everything}`));
-        expect(others.some((other) => other !== first)).toBe(true);
-      }
-      await page.goto("./");
-      await expect.poll(() => new URL(page.url()).searchParams.get("seed")).toMatch(/^\d+$/);
-    });
-
-    test("all right answers give the full score, then the solutions show", async ({ page }) => {
-      await page.goto("./");
-      if (quiz.questions.length > 1) await page.locator(".quiz-start button").click();
-      expect(await page.evaluate(() => Object.keys(localStorage))).toEqual([]);
-      for (let step = 0; step < quiz.questions.length; step++) {
-        const id = await page.locator(".question:visible").getAttribute("data-id");
-        const item = quiz.questions.find((candidate) => candidate.id === id);
-        if (item === undefined) throw new Error(`no visible question at step ${step + 1}`);
-        await answerQuestion(page, item, rightAnswer(item));
-        await question(page, item).locator(".question-next").click();
-      }
-      const total = String(quiz.questions.length);
-      await expect(page.locator(".quiz-score")).toHaveText(
-        de.score.replace("{score}", total).replace("{total}", total),
-      );
-      await expect(page.locator("#loesungen")).toBeVisible();
-      // only the last result, and only when the bank asks for it, under the app's own prefix
-      const stored = await page.evaluate(() => Object.keys(localStorage));
-      if (quiz.rememberLastResult === true) {
-        expect(stored).toHaveLength(1);
-        expect(stored[0]).toMatch(/^lernapps:.+:last-result$/);
-      } else {
-        expect(stored).toEqual([]);
-      }
-    });
+    if (!content)
+      test("all right answers give the full score, then the solutions show", async ({ page }) => {
+        await page.goto("./");
+        if (quiz.questions.length > 1) await page.locator(".quiz-start button").click();
+        expect(await page.evaluate(() => Object.keys(localStorage))).toEqual([]);
+        for (let step = 0; step < quiz.questions.length; step++) {
+          const id = await page.locator(".question:visible").getAttribute("data-id");
+          const item = quiz.questions.find((candidate) => candidate.id === id);
+          if (item === undefined) throw new Error(`no visible question at step ${step + 1}`);
+          await answerQuestion(page, item, rightAnswer(item));
+          await question(page, item).locator(".question-next").click();
+        }
+        const total = String(quiz.questions.length);
+        await expect(page.locator(".quiz-score")).toHaveText(
+          de.score.replace("{score}", total).replace("{total}", total),
+        );
+        await expect(page.locator("#loesungen")).toBeVisible();
+        // only the last result, and only when the bank asks for it, under the app's own prefix
+        const stored = await page.evaluate(() => Object.keys(localStorage));
+        if (quiz.rememberLastResult === true) {
+          expect(stored).toHaveLength(1);
+          expect(stored[0]).toMatch(/^lernapps:.+:last-result$/);
+        } else {
+          expect(stored).toEqual([]);
+        }
+      });
 
-    if (quiz.questions.length > 1) {
+    if (!content && quiz.questions.length > 1) {
       test("the learner chooses how many questions to answer; the address keeps the choice", async ({ page }) => {
         await page.goto("./?seed=11");
         await expect(page.locator(".quiz-start")).toBeVisible();
@@ -163,70 +210,60 @@ export function quizTests(bank = "src/quiz.json"): void {
       });
     }
 
-    test.describe("without JavaScript", () => {
-      test.use({ javaScriptEnabled: false });
-
-      test("every question and its solution can be read", async ({ page }) => {
-        await page.goto("./");
-        for (const item of quiz.questions) {
-          await expect(question(page, item).locator("legend")).toHaveText(item.text);
-          await expectMaterial(page, item, { loaded: false });
-          await expectBackground(page.locator(`#loesung-${item.id}`), item);
-        }
-      });
-    });
-
     for (const lang of languages.slice(1)) {
       const local = quizIn(all, lang);
       const words = messagesOf(lang);
       const address = `./${lang}/`;
 
       test.describe(`in ${lang}`, () => {
-        test.describe("without JavaScript", () => {
-          test.use({ javaScriptEnabled: false });
-
-          test(`the page is in ${lang}, every question and its solution can be read, the switch leads to every language`, async ({
-            page,
-          }) => {
-            await page.goto(address);
-            await expect(page.locator("html")).toHaveAttribute("lang", lang);
-            await expect(page.locator("h1")).toHaveText(local.title);
-            await expect(page.locator("#loesungen h2")).toHaveText(words.solutions);
-            for (const item of local.questions) {
-              await expect(question(page, item).locator("legend")).toHaveText(item.text);
-              await expectMaterial(page, item, { loaded: false });
-              await expectBackground(page.locator(`#loesung-${item.id}`), item);
-            }
-            for (const other of languages) {
-              await expect(page.locator(`link[rel="alternate"][hreflang="${other}"]`)).toHaveCount(1);
-            }
-            for (const other of languages.filter((candidate) => candidate !== lang)) {
+        if (content)
+          test.describe("without JavaScript", () => {
+            test.use({ javaScriptEnabled: false });
+
+            test(`the page is in ${lang}, every question and its solution can be read, the switch leads to every language`, async ({
+              page,
+            }) => {
               await page.goto(address);
-              await page.locator(`.page-languages a[hreflang="${other}"]`).click();
-              await expect(page.locator("html")).toHaveAttribute("lang", other);
-              await expect(page.locator("h1")).toHaveText(quizIn(all, other).title);
-              await expect(page.locator('.page-languages a[aria-current="page"]')).toHaveAttribute("hreflang", other);
-            }
+              await expect(page.locator("html")).toHaveAttribute("lang", lang);
+              await expect(page.locator("h1")).toHaveText(local.title);
+              await expect(page.locator("#loesungen h2")).toHaveText(words.solutions);
+              for (const item of local.questions) {
+                await expect(question(page, item).locator("legend")).toHaveText(item.text);
+                await expectMaterial(page, item, { loaded: false });
+                await expectBackground(page.locator(`#loesung-${item.id}`), item);
+              }
+              for (const other of languages) {
+                await expect(page.locator(`link[rel="alternate"][hreflang="${other}"]`)).toHaveCount(1);
+              }
+              for (const other of languages.filter((candidate) => candidate !== lang)) {
+                await page.goto(address);
+                await page.locator(`.page-languages a[hreflang="${other}"]`).click();
+                await expect(page.locator("html")).toHaveAttribute("lang", other);
+                await expect(page.locator("h1")).toHaveText(quizIn(all, other).title);
+                await expect(page.locator('.page-languages a[aria-current="page"]')).toHaveAttribute("hreflang", other);
+              }
+            });
           });
-        });
 
-        test(`what a question shows, in ${lang}`, async ({ page }) => {
-          const item = local.questions.find((candidate) => candidate.material !== undefined);
-          test.skip(item === undefined, "no question shows content");
-          if (item === undefined) return;
-          await page.goto(`${address}#${questionId(item)}`);
-          await expectMaterial(page, item);
-        });
+        if (content)
+          test(`what a question shows, in ${lang}`, async ({ page }) => {
+            const item = local.questions.find((candidate) => candidate.material !== undefined);
+            test.skip(item === undefined, "no question shows content");
+            if (item === undefined) return;
+            await page.goto(`${address}#${questionId(item)}`);
+            await expectMaterial(page, item);
+          });
 
-        test(`one question, answered in ${lang}`, async ({ page }) => {
-          const item = local.questions[0];
-          if (item === undefined) throw new Error("the quiz has no questions");
-          await page.goto(`${address}#${questionId(item)}`);
-          await expect(question(page, item)).toBeVisible();
-          await answerQuestion(page, item, rightAnswer(item), lang);
-          await expect(question(page, item).locator(".question-feedback")).toContainText(words.right);
-          await expectBackground(question(page, item).locator(".question-reveal"), item);
-        });
+        if (!content)
+          test(`one question, answered in ${lang}`, async ({ page }) => {
+            const item = local.questions[0];
+            if (item === undefined) throw new Error("the quiz has no questions");
+            await page.goto(`${address}#${questionId(item)}`);
+            await expect(question(page, item)).toBeVisible();
+            await answerQuestion(page, item, rightAnswer(item), lang);
+            await expect(question(page, item).locator(".question-feedback")).toContainText(words.right);
+            await expectBackground(question(page, item).locator(".question-reveal"), item);
+          });
       });
     }
   });

package/runtime/shared/questions/question.ts

@@ -20,6 +20,8 @@ export interface Option<T extends Text = string> {
   text: T;
   correct: boolean;
   info: T;
+  /** The option spoken, as its radio or checkbox is named: for an option that is only a formula; else made from it. */
+  alt?: T;
   link?: Link<T>;
 }
 
@@ -209,6 +211,7 @@ export function questionIn(question: Question<Text>, lang: string): Question {
           text: t(option.text),
           correct: option.correct,
           info: t(option.info),
+          ...(option.alt === undefined ? {} : { alt: t(option.alt) }),
           ...(option.link === undefined ? {} : { link: link(option.link) }),
         })),
       };

package/runtime/shared/questions/question.v1.schema.json

@@ -190,6 +190,10 @@
                 "description": "One to three sentences of background on this option itself, true whether or not it is the right answer, e.g. \"Der Uluru ist ein Inselberg in der Wüste Zentralaustraliens ...\". After an answer it shows for every option. For a wrong option it is also the reason a learner who chose it reads with the feedback, so say there why it does not fit.",
                 "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
               },
+              "alt": {
+                "description": "Optional: the option as it is spoken, for the name of its radio button or checkbox, when its text is only a formula, e.g. \"zwei hoch sieben\" for \"$2^7$\". Without it the name is made from the formula in the page's language (\"2 hoch 7\"); write it where that reads badly, e.g. for a chemical formula. Not needed when the text has words.",
+                "$ref": "urn:lernapps:schema:text.v1#/$defs/text"
+              },
               "link": {
                 "description": "Further reading on this option.",
                 "$ref": "#/$defs/link"

package/runtime/shared/questions/render.ts

@@ -44,17 +44,22 @@ export function questionWords(lang = "de"): Words {
 /** How a learner text becomes HTML. */
 export type Format = (text: string) => string;
 
-function controls(question: Question, { t }: Words, format: Format): string {
+/** A text as words for a name, where the text itself has none (a formula); undefined where it has. */
+export type Describe = (text: string) => string | undefined;
+
+function controls(question: Question, { t }: Words, format: Format, describe?: Describe): string {
   const name = questionId(question);
   switch (question.type) {
     case "single-choice":
     case "multiple-choice": {
       const type = question.type === "single-choice" ? "radio" : "checkbox";
       return question.options
-        .map(
-          (option, index) =>
-            `<label class="question-option"><input type="${type}" name="${name}" value="${index}"> <span>${format(option.text)}</span></label>`,
-        )
+        .map((option, index) => {
+          // an option that is only a formula has no text to name its control; the page says in words what it shows
+          const spoken = option.alt ?? describe?.(option.text);
+          const label = spoken === undefined ? "" : ` aria-label="${escape(spoken)}"`;
+          return `<label class="question-option"><input type="${type}" name="${name}" value="${index}"${label}> <span>${format(option.text)}</span></label>`;
+        })
         .join("\n");
     }
     case "true-false":
@@ -111,6 +116,8 @@ function controls(question: Question, { t }: Words, format: Format): string {
 export interface RenderQuestionOptions {
   /** How a learner text becomes HTML, e.g. with its formulas; escaped as plain text by default. */
   format?: (text: string) => string;
+  /** The words a screen reader names the control of an option by, when its text is only a formula. */
+  describe?: Describe;
   element?: "div" | "li";
   next?: boolean;
   lang?: string;
@@ -142,6 +149,7 @@ export function renderQuestion(
     materialHtml,
     explanationHtml,
     format = escape,
+    describe,
   }: RenderQuestionOptions = {},
 ): string {
   const words = questionWords(lang);
@@ -156,7 +164,7 @@ export function renderQuestion(
     ...(materialHtml === undefined || materialHtml === ""
       ? []
       : [`<div class="question-material">${materialHtml}</div>`]),
-    controls(question, words, format),
+    controls(question, words, format, describe),
     `</fieldset>`,
     `<div class="question-feedback" role="status"></div>`,
     `<div class="question-reveal" hidden>`,

package/runtime/shared/text/markdown.ts

@@ -158,7 +158,7 @@ export function renderInline(source: string, resolve: (href: string) => string):
 /** A plain text as HTML. */
 export const plain = escape;
 
-const FORMULA = /\$((?:\\.|[^\\$\n])+?)\$/g;
+export const FORMULA = /\$((?:\\.|[^\\$\n])+?)\$/g;
 
 /** A plain text as HTML in which only $…$ is a formula (MathML); everything else stays text, as in a quiz. */
 export function renderWithFormulas(text: string): string {

package/runtime/shared/text/speech.ts

@@ -0,0 +1,39 @@
+// The text alternative of a formula, for a name a screen reader or the accessibility check can read where the page has
+// only MathML (an option of a choice whose text is a formula, see the label of its radio): Speech Rule Engine speaks
+// the MathML of the formula in the page's language. Build time only; the engine loads its rules for every language
+// of the runtime once, here, so that speaking a formula in any of them is then synchronous.
+// @ts-expect-error speech-rule-engine ships no types; the part this file uses is typed below (drop this line if it does)
+import untyped from "speech-rule-engine";
+import { isLanguage, LANGUAGES } from "../languages.ts";
+import { renderFormula } from "./formula.ts";
+import { FORMULA } from "./markdown.ts";
+
+/** The part of Speech Rule Engine that this file uses. */
+interface Engine {
+  /** Loads the rules of the locale; once loaded, switching to it takes effect at once. */
+  setupEngine(setup: { locale: string; domain: string; modality: string }): Promise<void>;
+  /** The words of a MathML string, in the locale set up last. */
+  toSpeech(mathml: string): string;
+}
+const SRE: Engine = untyped;
+
+const SPEECH = { domain: "clearspeak", modality: "speech" } as const;
+
+for (const locale of LANGUAGES) await SRE.setupEngine({ locale, ...SPEECH });
+
+/** The formula `tex` as words in `lang` (German for a language the runtime has no texts for), e.g. "2 hoch 7". */
+export function speakFormula(tex: string, lang: string): string {
+  // the rules of every language are loaded: switching to one takes effect at once
+  void SRE.setupEngine({ locale: isLanguage(lang) ? lang : "de", ...SPEECH });
+  return SRE.toSpeech(renderFormula(tex, false)).replace(/\s+/g, " ").trim();
+}
+
+/**
+ * The words of a text that is only formulas, $…$ (and space); undefined for any other text, which has words of its own
+ * for a name to be made of.
+ */
+export function formulaAlternative(text: string, lang: string): string | undefined {
+  const formulas = [...text.matchAll(FORMULA)];
+  if (formulas.length === 0 || text.replace(FORMULA, "").trim() !== "") return undefined;
+  return formulas.map((formula) => speakFormula(formula[1] ?? "", lang)).join(" ");
+}

package/scaffold/explainer/src/app.yaml

@@ -0,0 +1,5 @@
+# yaml-language-server: $schema=../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json
+title: Platzhalter
+intro: Dieses Kapitel hält den Platz frei, bis der geplante Inhalt da ist.
+languages: [de]
+chapters: [thema]

package/scaffold/explainer/src/thema/chapter.yaml

@@ -0,0 +1,4 @@
+# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json
+title: Thema
+summary: Ersetze dieses Kapitel durch das erste geplante.
+pages: [einstieg]

package/scaffold/explainer/src/thema/einstieg.yaml

@@ -0,0 +1,28 @@
+# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json
+title: Einstieg
+description: Eine Seite, die den Platz frei hält.
+blocks:
+  - type: section
+    id: worum-es-geht
+    title: Worum es geht
+    blocks:
+      - type: text
+        text: Ersetze diese Seite durch die erste geplante.
+  - type: section
+    id: uebung
+    title: Übung
+    blocks:
+      - type: single-choice
+        id: platzhalter
+        text: Welche Antwort ist richtig?
+        explanation: Diese Übung ist ein Platzhalter. Ersetze sie durch die erste geplante.
+        links:
+          - title: lernapps.net
+            url: https://lernapps.net/
+        options:
+          - text: Diese
+            correct: true
+            info: "Richtig: Diese Antwort ist als richtig markiert."
+          - text: Diese nicht
+            correct: false
+            info: "Falsch: Diese Antwort ist als falsch markiert."

package/scaffold/interactive/src/app.yaml

@@ -0,0 +1,8 @@
+# yaml-language-server: $schema=../node_modules/@lernapps/app-templates/runtime/interactive/interactive.v1.schema.json
+title: Platzhalter
+description: Ein Knopf, der bis drei zählt. Er hält den Platz frei, bis die geplante App da ist.
+howto: |
+  - Drücke „Weiter“, bis du bei drei bist.
+competencies:
+  - Ich kann bis drei zählen.
+languages: [de]

package/scaffold/interactive/src/core/index.ts

@@ -0,0 +1,23 @@
+// The app's logic, a placeholder: a count from 0 to 3, one step for each "weiter" (the button of the component).
+// Pure TypeScript without DOM; the runtime keeps the state and calls start and step
+// (@lernapps/app-templates/interactive). Replace it with the planned core.
+import type { Input } from "@lernapps/app-templates/interactive";
+
+export interface State {
+  seed: number;
+  count: number;
+  done: boolean;
+}
+
+/** How far the count goes. */
+export const GOAL = 3;
+
+export function start(seed: number): State {
+  return { seed, count: 0, done: false };
+}
+
+export function step(state: State, input: Input): State {
+  if (state.done || input.kind !== "action" || input.name !== "weiter") return state;
+  const count = state.count + 1;
+  return { ...state, count, done: count >= GOAL };
+}

package/scaffold/interactive/src/messages/de.json

@@ -0,0 +1,6 @@
+{
+  "app": "Zähler",
+  "count": "{count} von {goal}",
+  "next": "Weiter",
+  "done": "Fertig: bis drei gezählt."
+}

package/scaffold/interactive/src/playthroughs/zaehlen.yaml

@@ -0,0 +1,12 @@
+# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/interactive/playthrough.v1.schema.json
+# Three times "weiter": the count reaches three and the app is done; a fourth press changes nothing.
+seed: 1
+steps:
+  - inputs: [{ kind: action, name: weiter }]
+    state: { count: 1, done: false }
+    announce: 1 von 3
+  - inputs: [{ kind: action, name: weiter }, { kind: action, name: weiter }]
+    state: { count: 3, done: true }
+    announce: "Fertig: bis drei gezählt."
+  - inputs: [{ kind: action, name: weiter }]
+    state: { count: 3, done: true }

package/scaffold/interactive/src/ui/App.vue

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+// A placeholder: the count and a button that emits the action "weiter". Replace it with the planned component.
+import { watch } from "vue";
+import { announce } from "@lernapps/tooling/a11y";
+import { translator } from "@lernapps/tooling/i18n";
+import type { Input } from "@lernapps/app-templates/interactive";
+import { GOAL, type State } from "../core/index.ts";
+import de from "../messages/de.json";
+
+const props = defineProps<{ state: State; lang: string }>();
+const emit = defineEmits<{ input: [input: Input] }>();
+const t = translator(de);
+
+watch(
+  () => props.state.count,
+  (count) => announce(props.state.done ? t("done") : t("count", { count, goal: GOAL })),
+);
+</script>
+
+<template>
+  <section :aria-label="t('app')">
+    <p>{{ state.done ? t("done") : t("count", { count: state.count, goal: GOAL }) }}</p>
+    <button v-if="!state.done" type="button" @click="emit('input', { kind: 'action', name: 'weiter' })">
+      {{ t("next") }}
+    </button>
+  </section>
+</template>