@lernapps/app-templates 0.1.1 → 0.2.1

package/README.md

@@ -7,7 +7,7 @@ with which a creator and their AI assistant build a learning app.
 ## Who it is for
 
 - **Creators and their assistants** never open this repo: the generator of
-  [lernapps/tooling](https://github.com/lernapps/tooling) copies a template folder into a new app. Start at
+  [lernapps/tooling](https://github.com/lernapps/tooling) writes a template's scaffold into a new app. Start at
   [lernapps.net/apps/eintragen/](https://lernapps.net/apps/eintragen/), or, as an assistant, at
   [lernapps.net/tooling/llms.txt](https://lernapps.net/tooling/llms.txt).
 - **Maintainers of an archetype** change its template and its runtime here.
@@ -24,7 +24,7 @@ feature: assistants read it before they choose an archetype.
 | [`explainer/`](explainer/) | an explainer: chapters of pages with sections, formulas, figures, tables, timelines, definitions with a glossary, quotes, code and YouTube videos behind two clicks, and an exercise on every page (the quiz's question types, and `generated` exercises drawn from a seed and property-tested at build), readable without JavaScript, in one or more languages; an optional self-assessment of the app or a chapter, checked as a whole; Vue components for what no block can express | the content as YAML in `src/`: `app.yaml`, a folder per chapter with `chapter.yaml` and its pages, `data/` and `images/`, and `components/` ([schema](runtime/explainer/explainer.v1.schema.json)) |
 | [`interactive/`](interactive/) | an interactive app whose doing is the content (a game, a trainer): a static start page, readable without JavaScript, and an app page with the app's own Vue components, its routes as `app/#<id>`; the build plays its playthroughs against its core | `src/app.yaml` ([schema](runtime/interactive/interactive.v1.schema.json)), the core `src/core/index.ts` (`start(seed, route)`, `step(state, input)` with a key or an action of its root component, optional `tick(state, dt)`), its components in `src/ui/`, data in `src/data/`, and `src/playthroughs/*.yaml` ([schema](runtime/interactive/playthrough.v1.schema.json)) |
 
-- [`runtime/`](runtime/): the runtime of each archetype, published to npm as `@lernapps/app-templates` (with the template folders, which `lernapps create` of `@lernapps/tooling` copies out of the installed package); its exports
+- [`runtime/`](runtime/): the runtime of each archetype, published to npm as `@lernapps/app-templates` (with the template folders, complete example apps, and the scaffold of each archetype: `lernapps create` of `@lernapps/tooling` copies the paths `lernapps.scaffold.<archetype>` in [`package.json`](package.json) lists and the placeholder in [`scaffold/<archetype>/`](scaffold/), and leaves the example in the installed package; [`scripts/scaffold.ts`](scripts/scaffold.ts) writes the same for the CI job `scaffold`); its exports
   are in [`package.json`](package.json), what each does in the comments of its source. The quiz's questions also work
   one by one, for other archetypes that embed them as exercises: `@lernapps/app-templates/quiz/question` (schema,
   validation, rendering, checker, messages; a question's texts may be maps by language), `startQuestion` of `@lernapps/app-templates/quiz` and the helpers of

package/dist/explainer-e2e.mjs

@@ -805,13 +805,32 @@ async function expectResultLine(request, copied, here, first, id, n) {
 	expect(response.status(), `${address} answers`).toBe(200);
 	expect(await response.text(), "the tutor page has the exercise").toContain(id);
 }
-/** The explainer's tests, for the content in `root`/src. */
+/**
+* The tests of an explainer's content, for the content in `root`/src: what every app runs (e2e/explainer.e2e.ts).
+* Without JavaScript every page as its content says, previous and next, the app's own components and the checks of
+* its exercise components. What the runtime does the same in every app is explainerRuntimeTests.
+*/
 function explainerTests(root = ".") {
+	explainerSuite(root, "content");
+}
+/**
+* The tests of the explainer's runtime on the content in `root`/src: the exercises of each type, the videos, the tutor
+* ways, the start page, the self-assessments, 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, not the app's content.
+*/
+function explainerRuntimeTests(root = ".") {
+	explainerSuite(root, "runtime");
+}
+/** Only at desktop width, in a test of what does not depend on the width; what a page shows is tested at 360 px too. */
+const desktopOnly = (page) => test.skip((page.viewportSize()?.width ?? 0) <= 400, "only at desktop width");
+function explainerSuite(root, part) {
 	const app = outline(root);
+	const content = part === "content";
 	test.describe("explainer", () => {
 		test.describe.configure({ mode: "parallel" });
 		test.use({ reducedMotion: "reduce" });
-		test.describe("without JavaScript", () => {
+		if (content) test.describe("without JavaScript", () => {
 			test.use({ javaScriptEnabled: false });
 			for (const lang of app.languages) {
 				for (const item of app.pages[lang] ?? []) test(`${item.url || "./"}: headings, sections, formulas, figures and anchors as in the content`, async ({ page }) => {
@@ -848,6 +867,7 @@ function explainerTests(root = ".") {
 					if (item.kind === "start") await expect(page.locator(".explainer-tutor-about h2")).toHaveText(message(item.lang, "tutorTitle"));
 				});
 				test(`${lang}: previous and next form one chain over all pages`, async ({ page }) => {
+					desktopOnly(page);
 					const order = (app.pages[lang] ?? []).map((item) => item.url);
 					const first = order[0];
 					if (first === void 0) throw new Error(`no page in ${lang}`);
@@ -881,7 +901,7 @@ function explainerTests(root = ".") {
 		});
 		test.describe("with JavaScript", () => {
 			test.skip(({ viewport }) => (viewport?.width ?? 0) > 400, "the exercises run at 360 px");
-			for (const item of app.pages["de"] ?? []) {
+			if (!content) for (const item of app.pages["de"] ?? []) {
 				const types = /* @__PURE__ */ new Map();
 				for (const exercise of item.exercises) if (!types.has(exercise.type)) types.set(exercise.type, exercise);
 				if (types.size === 0) continue;
@@ -895,13 +915,13 @@ function explainerTests(root = ".") {
 					expect(kept.length, "an answer per open task").toBe(types.has("open-task") ? 1 : 0);
 				});
 			}
-			for (const item of app.pages["de"] ?? []) {
+			if (!content) for (const item of app.pages["de"] ?? []) {
 				if (item.videos.length === 0) continue;
 				test(`${item.url}: the videos load nothing before a click, the player after it, directly once chosen`, async ({ page, baseURL }) => {
 					await checkVideos(page, item, new URL(baseURL ?? page.url()).origin);
 				});
 			}
-			for (const item of app.pages["de"] ?? []) {
+			if (content) for (const item of app.pages["de"] ?? []) {
 				if (item.components.length === 0) continue;
 				test(`${item.url}: each component hydrates without a console error (${item.components.map((component) => component.name).join(", ")})`, async ({ page }) => {
 					await checkComponents(page, item);
@@ -909,6 +929,7 @@ function explainerTests(root = ".") {
 				});
 			}
 		});
+		if (content) return;
 		for (const item of (app.pages["de"] ?? []).filter((candidate) => candidate.exercises.some((exercise) => exercise.kind === "generated"))) test(`${item.url}: the address holds the task of each exercise, and the tutor button gives them to the prompt`, async ({ page }) => {
 			await page.addInitScript(() => {
 				const copied = [];
@@ -1308,4 +1329,4 @@ function explainerTests(root = ".") {
 		});
 	});
 }
-export { explainerTests };
+export { explainerRuntimeTests, explainerTests };

package/dist/quiz-e2e.mjs

@@ -8,14 +8,53 @@ import { readFileSync } from "node:fs";
 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.
+*/
 function quizTests(bank = "src/quiz.json") {
+	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).
+*/
+function quizRuntimeTests(bank = "src/quiz.json") {
+	quizSuite(bank, "runtime");
+}
+function quizSuite(bank, part) {
+	const content = part === "content";
 	const all = JSON.parse(readFileSync(bank, "utf8"));
 	const languages = quizLanguages(all);
 	const quiz = quizIn(all, "de");
 	test.describe("quiz", () => {
 		test.use({ reducedMotion: "reduce" });
-		for (const item of quiz.questions) {
+		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 !== void 0) 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();
@@ -34,10 +73,6 @@ function quizTests(bank = "src/quiz.json") {
 					await expect(reveal.locator(".question-badge-right").first()).toHaveText(de.rightOption);
 				} else await expect(reveal).toContainText(de.rightAnswer);
 			});
-			if (item.material !== void 0) test(`${item.id} (${item.type}): what it shows is there, and its images load`, async ({ page }) => {
-				await page.goto(`./#${questionId(item)}`);
-				await expectMaterial(page, item);
-			});
 			test(`${item.id} (${item.type}): a wrong answer does not count`, async ({ page }) => {
 				await page.goto(`./#${questionId(item)}`);
 				await answerQuestion(page, item, wrongAnswer(item));
@@ -47,7 +82,7 @@ function quizTests(bank = "src/quiz.json") {
 				if (item.type === "single-choice" || item.type === "multiple-choice") await expect(question(page, item).locator(".question-badge-chosen").first()).toHaveText(de.yourChoice);
 			});
 		}
-		test("the seed in the address gives the order; without one, the address gets one", async ({ page }) => {
+		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) => {
 				await page.goto(address);
@@ -69,7 +104,7 @@ function quizTests(bank = "src/quiz.json") {
 			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 }) => {
+		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([]);
@@ -89,7 +124,7 @@ function quizTests(bank = "src/quiz.json") {
 				expect(stored[0]).toMatch(/^lernapps:.+:last-result$/);
 			} else expect(stored).toEqual([]);
 		});
-		if (quiz.questions.length > 1) test("the learner chooses how many questions to answer; the address keeps the choice", async ({ page }) => {
+		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();
 			await expect(page.locator(".question:visible")).toHaveCount(0);
@@ -113,23 +148,12 @@ function quizTests(bank = "src/quiz.json") {
 			await expect(page.locator(".question")).toHaveCount(1);
 			await expect(page.locator(".question")).toHaveAttribute("data-id", item.id);
 		});
-		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", () => {
+				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);
@@ -151,14 +175,14 @@ function quizTests(bank = "src/quiz.json") {
 						}
 					});
 				});
-				test(`what a question shows, in ${lang}`, async ({ page }) => {
+				if (content) test(`what a question shows, in ${lang}`, async ({ page }) => {
 					const item = local.questions.find((candidate) => candidate.material !== void 0);
 					test.skip(item === void 0, "no question shows content");
 					if (item === void 0) return;
 					await page.goto(`${address}#${questionId(item)}`);
 					await expectMaterial(page, item);
 				});
-				test(`one question, answered in ${lang}`, async ({ page }) => {
+				if (!content) test(`one question, answered in ${lang}`, async ({ page }) => {
 					const item = local.questions[0];
 					if (item === void 0) throw new Error("the quiz has no questions");
 					await page.goto(`${address}#${questionId(item)}`);
@@ -171,4 +195,4 @@ function quizTests(bank = "src/quiz.json") {
 		}
 	});
 }
-export { answerQuestion, expectBackground, expectFeedbackInView, expectMaterial, quizTests };
+export { answerQuestion, expectBackground, expectFeedbackInView, expectMaterial, quizRuntimeTests, quizTests };

package/docs/arc42/09-decisions.arc42.md

@@ -228,6 +228,30 @@ addresses: qg-understandable
 :::
 ```
 
+## A New App Gets the Scaffold, Not the Example
+
+`lernapps create` copies only the scaffold of the archetype into a new app: the paths that `lernapps.scaffold.<archetype>`
+in this package's `package.json` lists (the entry, the configuration, the e2e entry) and a placeholder as start content
+(`scaffold/<archetype>/`: one question, one page with one exercise, or a counter as the core). The template folder
+stays a complete example app, which this repo checks; an app does not copy it, the creator's assistant looks it up in
+`node_modules/@lernapps/app-templates/<archetype>/`. A copied example shaped the new app too much: its structure,
+its topic and its tone stayed long after the plan said otherwise. The list is data in this package, which alone knows
+what is configuration and what is example; the tooling only reads it. The CI job `scaffold` checks the scaffold as an
+app, so that a new app passes `lernapps check` from its first commit. `lernapps update` never writes the scaffold
+again: it moves libraries, not content. Rejected: a function `scaffold()` exported by the package, which would need the
+built package even in a clone given to `create --templates`; start content inside the template folder, which the
+template's own checks would read as part of the example.
+
+```arc42
+:::decision
+id: dec-scaffold
+title: A new app gets the scaffold and a placeholder, not the example app
+status: accepted
+date: 2026-11-02
+addresses: qg-understandable
+:::
+```
+
 ## Tutor Variant
 
 The optional tutor is a handoff to the learner's own assistant: after a click, a prompt (copied or passed to a chosen

package/explainer/docs/arc42/05-explainer-building-blocks.arc42.md

@@ -488,8 +488,12 @@ path: runtime/explainer/assessment.ts
 
 ### End-to-end tests
 
-Built. `explainerTests()` derives from the content what every page must show, checks it without JavaScript in every
-language, and with JavaScript one exercise per type and page and every component.
+Built, in two parts. `explainerTests()` checks the app's content: it derives from the content what every page must
+show and checks it without JavaScript in every language, previous and next, and with JavaScript the app's own
+components and the checks of its exercise components. `explainerRuntimeTests()` checks the runtime, the same in every
+app: one exercise per type and page, the videos, the tutor ways, the start page, the self-assessments, what is stored.
+Only this repo runs the second part, on the template and its fixtures (`explainer/e2e/runtime.e2e.ts`, not in the
+scaffold).
 
 ```arc42
 :::building-block
@@ -504,7 +508,7 @@ requires: if-archetype-content, if-runtime-texts, if-questions
 
 #### Tests interface
 
-The app's `e2e/explainer.e2e.ts` only calls `explainerTests()`.
+The app's `e2e/explainer.e2e.ts`, part of the scaffold, only calls `explainerTests()`.
 
 ```arc42
 :::interface

package/explainer/e2e/runtime.e2e.ts

@@ -0,0 +1,6 @@
+import { explainerRuntimeTests } from "@lernapps/app-templates/explainer/e2e";
+
+// The tests of the explainer runtime, which this repo runs on the template and its fixtures. Not part of the scaffold
+// (lernapps.scaffold in the package.json of @lernapps/app-templates): a new app runs only explainerTests(), on its
+// content.
+explainerRuntimeTests();

package/explainer/package.json

@@ -9,10 +9,11 @@
   },
   "devDependencies": {
     "@lernapps/app-templates": "file:..",
-    "@lernapps/tooling": "^0.1.2",
+    "@lernapps/tooling": "0.1.3",
     "vite-plus": "1.4.0"
   },
   "overrides": {
+    "@lernapps/app-templates": "file:..",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0"
   }
 }

package/interactive/package.json

@@ -9,10 +9,11 @@
   },
   "devDependencies": {
     "@lernapps/app-templates": "file:..",
-    "@lernapps/tooling": "^0.1.2",
+    "@lernapps/tooling": "0.1.3",
     "vite-plus": "1.4.0"
   },
   "overrides": {
+    "@lernapps/app-templates": "file:..",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lernapps/app-templates",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "The templates of the archetypes of lernapps.net apps, and the runtime of each archetype that apps depend on (the quiz: engine, build step, styles, end-to-end tests, the schema of the question bank, the questions it shares with the explainer are in ./questions; the explainer: build step, client module with its exercises, the islands of its Vue components, styles, end-to-end tests, the schema of its content; the interactive archetype: build step, the start page and the app page around the app's own Vue components and core, its playthroughs, styles, end-to-end tests, the schemas of its start page and its playthroughs)",
   "license": "MIT",
   "repository": {
@@ -14,6 +14,7 @@
     "explainer",
     "interactive",
     "quiz",
+    "scaffold",
     "!**/package-lock.json",
     "!**/node_modules"
   ],
@@ -142,6 +143,40 @@
       "explainer",
       "interactive",
       "quiz"
-    ]
+    ],
+    "scaffold": {
+      "explainer": [
+        ".gitignore",
+        "index.html",
+        "package.json",
+        "tsconfig.json",
+        "vite.config.ts",
+        "playwright.config.ts",
+        "src/main.ts",
+        "e2e/explainer.e2e.ts"
+      ],
+      "interactive": [
+        ".arc42ignore",
+        ".gitignore",
+        "index.html",
+        "package.json",
+        "tsconfig.json",
+        "vite.config.ts",
+        "playwright.config.ts",
+        "src/main.ts",
+        "src/env.d.ts",
+        "e2e/interactive.e2e.ts"
+      ],
+      "quiz": [
+        ".gitignore",
+        "index.html",
+        "package.json",
+        "tsconfig.json",
+        "vite.config.ts",
+        "playwright.config.ts",
+        "src/main.ts",
+        "e2e/quiz.e2e.ts"
+      ]
+    }
   }
 }

package/quiz/docs/arc42/05-quiz-building-blocks.arc42.md

@@ -196,8 +196,12 @@ path: runtime/quiz/engine.ts
 
 ### End-to-end tests
 
-Built. `quizTests()` checks every question of the bank in the browser (deep link, right and wrong answer, feedback in
-view with the focus), the full score, the page without JavaScript, and each further language.
+Built, in two parts. `quizTests()` checks the app's content: each question's deep link with what it shows, the page
+without JavaScript with every question and its solution, and each further language. `quizRuntimeTests()` checks the
+runtime, the same in every app: right and wrong answer with the feedback in view and the focus, the seed and the order,
+the run to the full score, the number of questions, what is stored. Only this repo runs the second part, on the
+template and its fixtures (`quiz/e2e/runtime.e2e.ts`, not in the scaffold): its time grows with the bank, and it tests
+nothing an app writes.
 
 ```arc42
 :::building-block
@@ -212,7 +216,7 @@ requires: if-archetype-content, if-runtime-texts
 
 #### Tests interface
 
-The app's `e2e/quiz.e2e.ts` only calls `quizTests()`.
+The app's `e2e/quiz.e2e.ts`, part of the scaffold, only calls `quizTests()`.
 
 ```arc42
 :::interface

package/quiz/e2e/runtime.e2e.ts

@@ -0,0 +1,5 @@
+import { quizRuntimeTests } from "@lernapps/app-templates/quiz/e2e";
+
+// The tests of the quiz runtime, which this repo runs on the template and its fixtures. Not part of the scaffold
+// (lernapps.scaffold in the package.json of @lernapps/app-templates): a new app runs only quizTests(), on its content.
+quizRuntimeTests();

package/quiz/package.json

@@ -9,10 +9,11 @@
   },
   "devDependencies": {
     "@lernapps/app-templates": "file:..",
-    "@lernapps/tooling": "^0.1.2",
+    "@lernapps/tooling": "0.1.3",
     "vite-plus": "1.4.0"
   },
   "overrides": {
+    "@lernapps/app-templates": "file:..",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0"
   }
 }