@lernapps/app-templates 0.0.1 → 0.1.1

package/dist/validate-Bxy9NfB8.mjs

@@ -0,0 +1,146 @@
+import { i as inLanguage } from "./html-mffkHGHh.mjs";
+import { n as markerOf } from "./block-BK_ohsH1.mjs";
+import { t as checkText } from "./check-CteIFN96.mjs";
+// runtime/shared/blocks/validate.ts
+/** The definition of each type of block in the schema of the blocks (blocks.v1.schema.json). */
+const MATERIAL_DEFINITIONS = {
+	text: "textBlock",
+	formula: "formula",
+	figure: "figure",
+	"labelled-figure": "labelledFigure",
+	table: "table",
+	quote: "quote",
+	code: "code"
+};
+/** Whether `text` names `marker`: as a word of its own, so that the marker A is not found in "Grundriss". */
+const names = (text, marker) => new RegExp(`(?<![\\p{L}\\p{N}])${marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\p{L}\\p{N}])`, "u").test(text);
+/** The problems of `blocks`. */
+function checkMaterial(blocks, checks) {
+	const problems = [];
+	const text = (at, value, kind) => {
+		if (value === void 0) return;
+		const { findings, links } = checkText(value, kind, checks.languages, checks.declaredIn);
+		for (const finding of findings) problems.push({
+			...finding,
+			path: [...at, ...finding.path]
+		});
+		for (const link of links) {
+			const place = [...at, ...link.path];
+			if (checks.onLink !== void 0) checks.onLink({
+				...link,
+				path: place
+			});
+			else problems.push({
+				path: place,
+				lang: link.lang,
+				message: `${link.href} is a link to a page of the app; here there are no pages: link an https address`
+			});
+		}
+	};
+	blocks.forEach((block, index) => {
+		const at = [index];
+		switch (block.type) {
+			case "text":
+				text([...at, "text"], block.text, "markdown");
+				break;
+			case "formula":
+				text([...at, "formula"], block.formula, "latex");
+				break;
+			case "figure":
+			case "labelled-figure":
+				if (block.type === "figure" && block.draw === void 0 === (block.image === void 0)) problems.push({
+					path: at,
+					message: block.draw === void 0 ? "draw or image is missing; a figure is drawn from data (draw) or a bundled image (image)" : "draw and image: a figure is either drawn from data or a bundled image"
+				});
+				if (block.image !== void 0 && !checks.imageExists(block.image)) problems.push({
+					path: [...at, "image"],
+					message: `${block.image} is missing: put the file into src/images/`
+				});
+				text([...at, "alt"], block.alt, "plain");
+				text([...at, "caption"], block.caption, "markdown");
+				if (block.type === "labelled-figure") {
+					const seen = /* @__PURE__ */ new Set();
+					block.labels.forEach((label, number) => {
+						text([
+							...at,
+							"labels",
+							number,
+							"text"
+						], label.text, "plain");
+						const marker = markerOf(label, number);
+						if (seen.has(marker)) problems.push({
+							path: [
+								...at,
+								"labels",
+								number,
+								"marker"
+							],
+							message: `${marker} is used twice; give each label its own marker`
+						});
+						seen.add(marker);
+					});
+					if (block.legend === false) for (const lang of checks.languages) {
+						const alt = inLanguage(block.alt, lang);
+						block.labels.forEach((label, number) => {
+							const marker = markerOf(label, number);
+							if (!names(alt, marker)) problems.push({
+								path: [...at, "alt"],
+								lang,
+								message: `alt does not name the marker ${marker}; with legend: false, alt names every marker with its part`
+							});
+						});
+					}
+				}
+				text([...at, "source"], block.source, "credit");
+				break;
+			case "table": {
+				text([...at, "caption"], block.caption, "plain");
+				block.header?.forEach((cell, number) => text([
+					...at,
+					"header",
+					number
+				], cell, "markdown"));
+				const columns = block.header?.length ?? block.rows[0]?.length ?? 0;
+				block.rows.forEach((row, line) => {
+					if (row.length !== columns) problems.push({
+						path: [
+							...at,
+							"rows",
+							line
+						],
+						message: `${row.length} cells, but the table has ${columns} columns; give each row a cell per column`
+					});
+					row.forEach((_cell, number) => text([
+						...at,
+						"rows",
+						line,
+						number
+					], row[number], "markdown"));
+				});
+				break;
+			}
+			case "quote":
+				text([...at, "text"], block.text, "markdown");
+				text([
+					...at,
+					"origin",
+					"author"
+				], block.origin.author, "name");
+				text([
+					...at,
+					"origin",
+					"work"
+				], block.origin.work, "name");
+				if (typeof block.origin.year !== "number") text([
+					...at,
+					"origin",
+					"year"
+				], block.origin.year, "plain");
+				text([...at, "source"], block.source, "credit");
+				break;
+			case "code": text([...at, "caption"], block.caption, "plain");
+		}
+	});
+	return problems;
+}
+export { checkMaterial as n, MATERIAL_DEFINITIONS as t };

package/dist/vue-DO1m6q1R.mjs

@@ -0,0 +1,40 @@
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+// runtime/shared/vue.ts
+const require = createRequire(import.meta.url);
+/** vue, and vue/<path>, resolved to the copy this runtime depends on. */
+const vueAlias = () => [{
+	find: /^vue(?=$|\/)/,
+	replacement: dirname(require.resolve("vue/package.json"))
+}];
+/** The options of @vitejs/plugin-vue: a component's scope id from its file and source alone, the same in the build and
+* in the server that renders it. */
+const VUE_OPTIONS = { features: { componentIdGenerator: "filepath-source" } };
+/** Loads modules of the app in `root` for Node in a Vite server of its own, with the components compiled for it. */
+async function withServer(root, act) {
+	const [{ createServer }, { default: vue }] = await Promise.all([import("vite-plus"), import("@vitejs/plugin-vue")]);
+	const server = await createServer({
+		root,
+		configFile: false,
+		logLevel: "silent",
+		plugins: [vue(VUE_OPTIONS)],
+		resolve: { alias: vueAlias() },
+		appType: "custom",
+		server: {
+			middlewareMode: true,
+			hmr: false,
+			ws: false,
+			watch: null
+		},
+		optimizeDeps: {
+			noDiscovery: true,
+			include: []
+		}
+	});
+	try {
+		return await act((id) => server.ssrLoadModule(id));
+	} finally {
+		await server.close();
+	}
+}
+export { vueAlias as n, withServer as r, VUE_OPTIONS as t };

package/dist/vue-code-BkJjW_I_.mjs

@@ -0,0 +1,320 @@
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, posix } from "node:path";
+// runtime/shared/vue-code.ts
+const require = createRequire(import.meta.url);
+let compiler;
+/** Vue's SFC compiler, loaded on first use: an app without components never loads it. */
+const sfc = () => compiler ??= require("vue/compiler-sfc");
+const TOOLING = [
+	"@lernapps/tooling/storage",
+	"@lernapps/tooling/i18n",
+	"@lernapps/tooling/a11y"
+];
+/** The packages a component may import, for a message. */
+const PACKAGES = `vue, @lernapps/app-templates, ${TOOLING.join(", ")}`;
+const NETWORK = /* @__PURE__ */ new Set([
+	"fetch",
+	"XMLHttpRequest",
+	"WebSocket",
+	"EventSource"
+]);
+const BROWSER = /* @__PURE__ */ new Set([
+	"window",
+	"document",
+	"navigator",
+	"location",
+	"history",
+	"localStorage",
+	"sessionStorage",
+	"indexedDB",
+	"matchMedia",
+	"requestAnimationFrame",
+	"cancelAnimationFrame",
+	"getComputedStyle",
+	"alert",
+	"confirm",
+	"prompt",
+	"screen",
+	"customElements",
+	"IntersectionObserver",
+	"ResizeObserver",
+	"MutationObserver"
+]);
+/** The hooks that never run while the build renders the component: inside them, browser globals are allowed. */
+const BROWSER_HOOKS = /* @__PURE__ */ new Set([
+	"onMounted",
+	"onBeforeUnmount",
+	"onUnmounted"
+]);
+const HTML = /* @__PURE__ */ new Set([
+	"innerHTML",
+	"outerHTML",
+	"insertAdjacentHTML"
+]);
+const GLOBAL_OBJECTS = /* @__PURE__ */ new Set([
+	"window",
+	"self",
+	"globalThis"
+]);
+/** A line of a problem in `file`, at `place` when it is known. */
+const line = (file, place, message) => `${file}${place === void 0 ? "" : `:${place.line}${place.column === void 0 ? "" : `:${place.column}`}`}: ${message}`;
+const isNode = (value) => typeof value === "object" && value !== null && typeof value.type === "string";
+/** Every node of `root`, with its parents from the root down. */
+function* nodes(root, parents = []) {
+	yield [root, parents];
+	for (const [key, value] of Object.entries(root)) {
+		if (key === "loc" || key === "leadingComments" || key === "trailingComments" || key === "innerComments") continue;
+		for (const child of Array.isArray(value) ? value : [value]) if (isNode(child)) yield* nodes(child, [...parents, root]);
+	}
+}
+const parse = (code) => sfc().babelParse(code, {
+	sourceType: "module",
+	plugins: ["typescript"]
+}).program;
+/** The name of a member's property: x.innerHTML, x["innerHTML"]. */
+function propertyName(node) {
+	if (node.type !== "MemberExpression" && node.type !== "OptionalMemberExpression") return void 0;
+	if (!node.computed && node.property.type === "Identifier") return node.property.name;
+	return node.property.type === "StringLiteral" ? node.property.value : void 0;
+}
+/** The import specifiers of `program`, with their nodes: static, re-exports and dynamic imports. */
+function imports(program) {
+	const found = [];
+	for (const [node] of nodes(program)) if (node.type === "ImportDeclaration" && node.importKind !== "type" || (node.type === "ExportNamedDeclaration" || node.type === "ExportAllDeclaration") && node.source !== null && node.source !== void 0 && node.exportKind !== "type") {
+		if (node.source) found.push({
+			source: node.source.value,
+			node
+		});
+	} else if (node.type === "CallExpression" && node.callee.type === "Import") {
+		const [argument] = node.arguments;
+		found.push({
+			source: argument?.type === "StringLiteral" ? argument.value : "(an expression)",
+			node
+		});
+	} else if (node.type === "ImportExpression") found.push({
+		source: node.source.type === "StringLiteral" ? node.source.value : "(an expression)",
+		node
+	});
+	return found;
+}
+/** The package a bare import specifier names: "yaml" for "yaml/util", "@scope/name" for "@scope/name/sub". */
+const packageOf = (source) => source.split("/").slice(0, source.startsWith("@") ? 2 : 1).join("/");
+/**
+* What the code of `program` may not do, and its imports of the app's own modules (`isLocal`); `own` names these for
+* a message, `packages` are the libraries it may import besides.
+*/
+function findings(program, isLocal, own, packages = []) {
+	const found = [];
+	const locals = [];
+	for (const { source, node } of imports(program)) if (/^[a-z][a-z0-9+.-]*:|^\/\//i.test(source)) found.push({
+		node,
+		message: `an import from ${source}; a component loads nothing from the network, so bundle what it needs (vue-component-no-network)`
+	});
+	else if (isLocal(source)) locals.push({
+		source,
+		node
+	});
+	else if (source !== "vue" && source !== "@lernapps/app-templates" && !source.startsWith("@lernapps/app-templates/") && !TOOLING.includes(source) && !packages.includes(packageOf(source))) found.push({
+		node,
+		message: `an import from ${source}; a component imports only from ${PACKAGES} and ${own} (vue-component-imports)`
+	});
+	const { walkIdentifiers } = sfc();
+	if (program.body.length === 0) return {
+		found,
+		locals
+	};
+	walkIdentifiers(program, (identifier, parent, parents, isReference, isLocal) => {
+		if (!isReference || isLocal) return;
+		const { name } = identifier;
+		if (NETWORK.has(name)) found.push({
+			node: identifier,
+			message: `${name}: a component makes no network request; give it what it needs through its props (vue-component-no-network)`
+		});
+		else if (name === "eval" || name === "Function" && (parent?.type === "NewExpression" || parent?.type === "CallExpression") && parent.callee === identifier) found.push({
+			node: identifier,
+			message: `${name === "eval" ? "eval" : "Function"}: a component runs no code from strings (vue-component-no-html-injection)`
+		});
+		else if (BROWSER.has(name)) {
+			const stack = [...parents, identifier];
+			if (!stack.some((node, index) => node.type === "CallExpression" && node.callee.type === "Identifier" && BROWSER_HOOKS.has(node.callee.name) && node.arguments.some((argument) => argument === stack[index + 1]))) found.push({
+				node: identifier,
+				message: `${name} outside onMounted; the build renders the component where there is no ${name}, so use it only inside onMounted (vue-component-browser-globals)`
+			});
+		}
+	});
+	for (const [node] of nodes(program)) {
+		const property = propertyName(node);
+		if (property !== void 0 && HTML.has(property)) found.push({
+			node,
+			message: `${property}: a component writes no HTML from strings; let the template render it (vue-component-no-html-injection)`
+		});
+		else if (property === "sendBeacon") found.push({
+			node,
+			message: `sendBeacon: a component makes no network request (vue-component-no-network)`
+		});
+		else if (property !== void 0 && NETWORK.has(property) && (node.type === "MemberExpression" || node.type === "OptionalMemberExpression") && node.object.type === "Identifier" && GLOBAL_OBJECTS.has(node.object.name)) found.push({
+			node,
+			message: `${property}: a component makes no network request; give it what it needs through its props (vue-component-no-network)`
+		});
+		else if (node.type === "ObjectProperty" && !node.computed && (node.key.type === "Identifier" && node.key.name === "innerHTML" || node.key.type === "StringLiteral" && node.key.value === "innerHTML")) found.push({
+			node,
+			message: `v-html: a component writes no HTML from strings; let the template render it (vue-component-no-html-injection)`
+		});
+	}
+	return {
+		found,
+		locals
+	};
+}
+/** The problem lines of `found`, each once, at its place; one without a place only when no other has the message. */
+function placed(file, found, place) {
+	const lines = [];
+	const withPlace = /* @__PURE__ */ new Set();
+	const without = [];
+	for (const finding of found) {
+		const at = place(finding.node);
+		if (at === void 0) without.push(finding.message);
+		else {
+			withPlace.add(finding.message);
+			const text = line(file, at, finding.message);
+			if (!lines.includes(text)) lines.push(text);
+		}
+	}
+	for (const message of new Set(without)) if (!withPlace.has(message)) lines.push(line(file, void 0, message));
+	return lines;
+}
+/** The libraries in the dependencies of the app's package.json, by their package names. */
+function dependencies(root) {
+	const file = join(root, "package.json");
+	if (!existsSync(file)) return [];
+	const manifest = JSON.parse(readFileSync(file, "utf8"));
+	return Object.keys(manifest.dependencies ?? {});
+}
+/**
+* The scope of an app whose components may import any of its files in src/ and the libraries in the dependencies of
+* its package.json (the interactive archetype).
+*/
+const sourceScope = (root) => ({
+	own: "the app's own files in src/ or a library in the dependencies of package.json",
+	packages: dependencies(root),
+	resolve(file, source) {
+		if (!source.startsWith("./") && !source.startsWith("../")) return void 0;
+		const target = posix.normalize(posix.join(dirname(file), source));
+		if (!target.startsWith("src/")) return { problem: `${source} is outside src/; a component imports only the app's own files in src/` };
+		return existsSync(join(root, target)) ? { file: target } : { problem: `${source} does not exist; import a file of src/, with its extension` };
+	}
+});
+/** A single-file component as the compiler reads it; undefined, with its problems, when it has none to check. */
+function readSfc(root, file, problems) {
+	const source = readFileSync(join(root, file), "utf8");
+	const { descriptor, errors } = sfc().parse(source, {
+		filename: join(root, file),
+		sourceMap: true
+	});
+	for (const error of errors) {
+		const loc = "loc" in error ? error.loc : void 0;
+		problems.push(line(file, loc ? {
+			line: loc.start.line,
+			column: loc.start.column
+		} : void 0, error.message));
+	}
+	if (errors.length > 0) return void 0;
+	const setup = descriptor.scriptSetup;
+	if (setup === null || setup.lang !== "ts") {
+		problems.push(line(file, void 0, `a component has <script setup lang="ts">`));
+		return;
+	}
+	return {
+		descriptor,
+		setup
+	};
+}
+/**
+* The checks of components' code, each problem into `problems`: `compile` compiles a component's <script setup> with
+* its template and checks the output, `module` checks a TypeScript module; each follows the imports of the app's own
+* TypeScript modules (`scope`) and checks each module once.
+*/
+function codeChecker(root, scope, problems) {
+	const { SourceMapConsumer } = require("source-map-js");
+	const checked = /* @__PURE__ */ new Set();
+	const check = (file, program) => {
+		const { found, locals } = findings(program, (source) => scope.resolve(file, source) !== void 0, scope.own, scope.packages);
+		for (const { source, node } of locals) {
+			const target = scope.resolve(file, source);
+			if (target === void 0) continue;
+			if ("problem" in target) found.push({
+				node,
+				message: target.problem
+			});
+			else if (target.file.endsWith(".ts")) module(target.file);
+		}
+		return found;
+	};
+	const module = (file) => {
+		if (checked.has(file)) return;
+		checked.add(file);
+		problems.push(...placed(file, check(file, parse(readFileSync(join(root, file), "utf8"))), (node) => node.loc ? {
+			line: node.loc.start.line,
+			column: node.loc.start.column + 1
+		} : void 0));
+	};
+	const compile = (file, descriptor) => {
+		let compiled;
+		try {
+			compiled = sfc().compileScript(descriptor, {
+				id: file.replace(/^.*\//, "").replace(/\.vue$/, ""),
+				inlineTemplate: true,
+				sourceMap: true,
+				isProd: true,
+				fs: {
+					fileExists: existsSync,
+					readFile: (name) => readFileSync(name, "utf8")
+				}
+			});
+		} catch (error) {
+			const loc = error.loc;
+			const message = (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
+			problems.push(line(file, loc ? {
+				line: loc.start.line,
+				column: loc.start.column
+			} : void 0, message));
+			return;
+		}
+		const program = parse(compiled.content);
+		const consumer = compiled.map ? new SourceMapConsumer(compiled.map) : void 0;
+		problems.push(...placed(file, check(file, program), (node) => {
+			if (!node.loc || consumer === void 0) return void 0;
+			const original = consumer.originalPositionFor({
+				line: node.loc.start.line,
+				column: node.loc.start.column
+			});
+			return original.line === null ? void 0 : {
+				line: original.line,
+				column: original.column + 1
+			};
+		}));
+		return {
+			program,
+			consumer
+		};
+	};
+	return {
+		module,
+		compile
+	};
+}
+/**
+* The checks of the components' code for the single-file components `files` (from the app's root) and the app's own
+* TypeScript modules they import (`scope`): one line per problem, with the file and its place.
+*/
+function codeProblems(root, files, scope) {
+	const problems = [];
+	const code = codeChecker(root, scope, problems);
+	for (const file of files) {
+		const read = readSfc(root, file, problems);
+		if (read !== void 0) code.compile(file, read.descriptor);
+	}
+	return problems;
+}
+export { parse as a, sourceScope as c, nodes as i, codeProblems as n, readSfc as o, line as r, sfc as s, codeChecker as t };

package/docs/arc42/01-introduction-and-goals.arc42.md

@@ -0,0 +1,82 @@
+# Introduction and Goals
+
+<!--
+Arc42 chapter 1. Describes the relevant requirements and the driving forces that
+architects and the development team must consider.
+
+This chapter has three subsections:
+
+1.1 Requirements Overview
+  Short description of the functional requirements and business goals — not a full
+  requirements spec. Write a compact summary or refer to an external requirements
+  document. A brief prose paragraph and/or a table of the most important use cases.
+
+1.2 Quality Goals
+  The top three to five quality goals for the architecture (highest-importance only).
+  Write a single sentence or short paragraph, then link to chapter 10.
+  Do NOT repeat the quality-goal blocks here — they live in 10-quality-requirements.arc42.md.
+
+  Example:
+
+  See [10-quality-requirements.arc42.md](10-quality-requirements.arc42.md) for the
+  complete quality catalog with priorities and measurable scenarios.
+
+1.3 Stakeholders
+  A table of all stakeholders: their role, contact, and expectations from the
+  architecture and its documentation. Think broadly — include teams that must
+  maintain the system, operators, auditors, and external partners.
+
+See https://docs.arc42.org/section-1/ for further guidance.
+
+Example:
+
+## 1.1 Requirements Overview
+
+Every app of lernapps.net is a small, frontend-only learning app, made by a creator with their AI assistant from one
+of three archetypes: a quiz about things to know (a question bank), an explainer (pages of content with an exercise on
+every page), or an interactive app in which doing is the content (a typing game, a Kniffel trainer, a proofreading
+app). The archetypes stay separate, but they share their quality goals and so one architecture: this generic
+architecture, which each archetype extends in its template folder (`quiz/docs/arc42/`, `explainer/docs/arc42/`,
+`interactive/docs/arc42/`). Every app has the same frame: static pages rendered at build in every declared language,
+the archetype's code in the browser started by a runtime the app does not change, build checks and end-to-end tests
+that come with the runtime, the tooling's helpers, and an optional tutor, which hands the current task to the
+learner's own AI assistant (no model runs in the browser). The app reaches learners through one entry in the
+lernapps.net app overview, which links to it.
+
+| Use case | Who | What the architecture must allow |
+| --- | --- | --- |
+| Find out what the app does | learner, teacher, parent | static pages in every declared language; what each archetype shows without JavaScript is in its extension |
+| Learn and practise | learner | the archetype's code in the browser, its state only on the device |
+| Open a part directly | learner, catalog entry | deep links (a question, a page and task, a mode or level), a seed in the address |
+| Build and extend the app | creator and their AI assistant | what the archetype lets the creator write, under rules the build and `lernapps check` verify |
+| Get help with a task | learner | an optional handoff of the task to the learner's own assistant, after a click |
+
+## 1.2 Quality Goals
+
+The top quality goals, in this order:
+
+- `qg-privacy`: the app sends nothing anywhere and requests nothing from another server before a click; what it
+  remembers stays on the learner's device.
+- `qg-checkable`: the rules an app keeps are verified by machine, at build and in the browser.
+- `qg-accessibility`: the pages meet WCAG 2.1 AA and work at 360 px by default; an app that cannot declares its
+  limits in its entry.
+- `qg-understandable`: a reviewer or the creator's agent understands an app's structure from its architecture.
+
+The set and the priorities (privacy and checkable high, accessibility and understandable medium) are the owner's
+(2026-10-16). The quiz and the explainer, both text-heavy, add readability without JavaScript as a goal of their own
+in their extensions.
+
+See [10-quality-requirements.arc42.md](10-quality-requirements.arc42.md) for the complete
+quality catalog with priorities and measurable scenarios.
+
+## 1.3 Stakeholders
+
+| Role | Contact | Expectations |
+| --- | --- | --- |
+| Learner (adults and students, often in German schools) | — | An app that works right away, in the browser, without an account, that keeps no data off the device and does not overwhelm |
+| Creator | the app's repo | To build and list an app with almost no effort, and to hear when it helped |
+| The creator's AI assistant | the app's repo, the `lernapps-*` skills | A clear frame: which parts are fixed, what the archetype lets it write, which rules the build checks |
+| Platform owner | Oliver Jägle (@mrsimpson), lernapps@beimir.net | Every app keeps the platform's rules (privacy, accessibility default, licences) so it can be listed without doubt |
+| Teachers and parents | lernapps.net | To see from the pages and the entry what the app teaches and what it does not offer, and that it may be used |
+| Reviewers (the review agent before listing, the owner who decides the listing) | `lernapps/apps` | An architecture that says what each part does and why, readable without the code |
+| Maintainers of an archetype | `lernapps/app-templates` | One generic architecture and one extension per archetype, so a change to the frame is made once |