@lernapps/tooling 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 the lernapps.net contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# tooling
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The tooling with which a creator and their AI assistant build a learning app for
+[lernapps.net](https://lernapps.net/): an app that runs in the browser, collects nothing, is accessible, and is
+listed in the app overview within minutes. The creator publishes the app at their own address, by default their own
+GitHub Pages; once listed, lernapps.net serves a copy of it at `lernapps.net/apps/start/<id>/`.
+
+The tooling is responsible for helping builders get their apps out. The [app overview](https://github.com/lernapps/apps)
+explains building and listing, and provides the apps themselves: the catalog.
+
+The repo also holds the platform's upkeep, which creators don't use: the actions that check, publish and preview
+lernapps.net's own websites, and the update policy for dependencies.
+
+## Who it is for
+
+- **Creators and their assistants** who build an app. The creator needs no development skills; the assistant
+  follows the guidance and the checks.
+- **The platform owner and the review agent**, who decide whether an app is listed.
+- **Maintainers of the lernapps repos**, who change the rules, the checks and the guidance.
+
+## Where to start
+
+- **Creators:** [lernapps.net/apps/build/](https://lernapps.net/apps/build/) says what to tell your assistant.
+- **Assistants:** read [lernapps.net/tooling/llms.txt](https://lernapps.net/tooling/llms.txt). It starts the build
+  with the plan template.
+- **The [skills](skills/):** one per phase, grouped by what they hold: `process/`, `tooling/`, `content/`,
+  `archetypes/`. The [platform rules](skills/tooling/lernapps-cli/references/platform-rules.md) hold for every app,
+  however it is built.
+- **The [plan template](guidance/plan-template.md):** the whole workflow of an app's first version, from the first
+  question to the listing. It names each skill at the step where it is needed. Every later change follows the
+  [increment template](guidance/increment-template.md), in a plan of its own.
+- **The [architecture](https://lernapps.net/tooling/architecture/):** what each part is responsible for and why.
+- **The [rule catalog](https://lernapps.net/tooling/rules/):** every rule by id, with where it is told and checked.
+
+## What is in it
+
+- **The package `@lernapps/tooling`**, on [npm](https://www.npmjs.com/package/@lernapps/tooling) (released from CI with provenance, `.github/workflows/release.yml`): the guidance, the skills, the shared preset
+  and lint rules of every app, and the CLI.
+- **The CLI `lernapps`:** `init` starts an app's plan in an empty folder and syncs the skills of the packages into the agent directories, `skills --archetype` adds those of the chosen archetype, `create` writes a new app for an archetype once the creator confirmed the plan, `check`
+  checks an app the same way in its git hooks and in CI, `update` moves an app to the runtime and tooling versions of the latest
+  tooling and replaces the app's `lernapps-*` skills with that tooling's (and an older app's single plan into
+  `.vibe/plans/`), `changes` tells what a change can affect, so that hooks and CI run only that, `screenshots` writes an image of every page and every figure of a built explainer or quiz, to show a creator what a learner sees (`npx lernapps screenshots --help`). `npx --yes @lernapps/tooling --help` before an app exists, `npx lernapps --help` in one.
+- **The actions in [`actions/`](actions/):** the app check, app publish and app preview actions of every app, and the site
+  actions with which lernapps.net's own websites are checked, published and previewed. Each says what it does in its
+  `action.yml`. The reusable workflow [`changes.yml`](.github/workflows/changes.yml) gives other workflows the
+  change scope, and its comments show how a required check never stays "Pending".
+- **The [documentation site](https://lernapps.net/tooling/):** the architecture, the rule catalog, the published
+  schemas and the `llms.txt`.
+- **The review** in [`review/`](review/): the procedure and rubric of the agent that reviews an app before listing.
+- **The Renovate preset** [`default.json`](default.json), which every lernapps repo extends.
+
+The details live where you use them: the help of each command, the description of each action, the error messages,
+and the comments in the code.
+
+## Contributing
+
+`npm ci`, then `npm run check` runs exactly what CI runs. The pre-push hook runs a fast subset when a push changes no code.
+
+## Links
+
+- [Documentation site](https://lernapps.net/tooling/), with the published schemas
+- [Platform design](https://lernapps.net/docs/platform-design/)
+- [App templates](https://github.com/lernapps/app-templates)
+- [App overview](https://github.com/lernapps/apps)
+
+## License
+
+[MIT](LICENSE)

package/archetypes/shared/a11y.ts

@@ -0,0 +1,38 @@
+// Accessibility helpers of a lernapps app (@lernapps/tooling/a11y): what interactive apps need beyond semantic HTML,
+// so that feedback reaches screen readers and keyboard users as it reaches everyone else.
+
+const regions = new Map<string, HTMLElement>();
+
+/** A visually hidden live region, created once per politeness. */
+function region(politeness: "polite" | "assertive"): HTMLElement {
+  const existing = regions.get(politeness);
+  if (existing?.isConnected) return existing;
+  const element = document.createElement("div");
+  element.setAttribute("aria-live", politeness);
+  element.setAttribute("aria-atomic", "true");
+  element.style.cssText =
+    "position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0";
+  document.body.append(element);
+  regions.set(politeness, element);
+  return element;
+}
+
+/** Says `text` to screen readers, e.g. the feedback after an answer; "assertive" interrupts, for errors only. */
+export function announce(text: string, politeness: "polite" | "assertive" = "polite"): void {
+  const live = region(politeness);
+  live.textContent = "";
+  // a new text node after the region is cleared, so that the same text is announced again
+  setTimeout(() => {
+    live.textContent = text;
+  }, 50);
+}
+
+/** Moves the keyboard focus to `element`, e.g. the heading of the next task, making it focusable if needed. */
+export function moveFocus(element: HTMLElement): void {
+  if (!element.matches("a[href], button, input, select, textarea, [tabindex]")) element.tabIndex = -1;
+  element.focus();
+}
+
+/** Whether the learner asked for less motion: animate only when this is false. */
+export const prefersReducedMotion = (): boolean =>
+  globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;

package/archetypes/shared/hooks/pre-commit

@@ -0,0 +1,22 @@
+# The pre-commit hook of every lernapps app (installed by the preset): formats the staged files, then runs
+# the fast part of the checks (format, lint, type check; an interactive app's architecture with arc42 diff), the
+# first half of what CI runs. npm install installs both hooks through the app's prepare script, as the generator
+# writes it: lernapps hooks (archetypes/shared/install-hooks.ts)
+# Quiet: everything the steps print goes to the log below. On success the hook prints nothing; on a failure it prints
+# one line: the step, its exit code and the log, which holds the full output. CI runs the same command and prints it.
+# A commit with nothing staged (the empty start commits of main and gh-pages) has nothing to format or check.
+git diff --cached --quiet && exit 0
+log=node_modules/.cache/lernapps/pre-commit.log
+mkdir -p "$(dirname "$log")"
+: >"$log"
+step() {
+  name=$1
+  shift
+  echo "\$ $*" >>"$log"
+  "$@" >>"$log" 2>&1 && return 0
+  code=$?
+  echo "lernapps pre-commit: $name failed (exit $code); the full output is in $log" >&2
+  exit "$code"
+}
+step "format the staged files (vp staged)" vp staged
+step "the fast checks (lernapps check --pre-commit)" lernapps check --pre-commit

package/archetypes/shared/hooks/pre-push

@@ -0,0 +1,4 @@
+# The pre-push hook of every lernapps app (installed by the preset): the heavy part of the checks (unit tests, build,
+# checks of the built app, end-to-end tests), the second half of what CI runs. A failure increments prePushFailures
+# in the plan file.
+lernapps check --pre-push

package/archetypes/shared/i18n.ts

@@ -0,0 +1,25 @@
+// Learner texts from the app's message files (@lernapps/tooling/i18n; lint rule learner-text-german): the app keeps
+// its texts in src/messages/de.json and shows them through a translator, never as strings in code.
+//
+//   import de from "./messages/de.json";
+//   const t = translator(de);
+//   t("solved", { count: 3 }); // "Du hast {count} Aufgaben gelöst." → "Du hast 3 Aufgaben gelöst."
+
+/** The texts of one language, by key. */
+export type Messages = Readonly<Record<string, string>>;
+/** Values for the placeholders of a text, `{name}`; numbers are formatted for the language. */
+export type Params = Readonly<Record<string, string | number>>;
+
+/** The text of `key`, with its placeholders filled; a placeholder without a value stays as it is. */
+export function translator<M extends Messages>(
+  messages: M,
+  locale = "de-DE",
+): (key: keyof M & string, params?: Params) => string {
+  const numbers = new Intl.NumberFormat(locale);
+  return (key, params = {}) =>
+    (messages[key] ?? key).replace(/\{(\w+)\}/g, (placeholder, name: string) => {
+      const value = params[name];
+      if (value === undefined) return placeholder;
+      return typeof value === "number" ? numbers.format(value) : value;
+    });
+}

package/archetypes/shared/install-hooks.ts

@@ -0,0 +1,63 @@
+// `lernapps hooks`: installs the git hooks of the preset (archetypes/shared/hooks/) into the app's repository, as
+// the app's prepare script runs it on every npm install. Only where the app's folder is the root of its git work
+// tree: a folder inside another repository (a template in lernapps/app-templates, an app in a monorepo) leaves that
+// repository's hooks alone, since vp config would point the whole repository at the app's hooks.
+//
+// git runs the hooks from a folder of their own below node_modules/.cache/, each a line that runs the preset's hook
+// of the installed tooling. Not from the package's folder: npm replaces that whenever the tooling moves to another
+// commit (lernapps update installs it by name, which runs no prepare script), and git skips a hooks folder that is gone
+// without a word, so the commits after an update would pass unchecked.
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { parseArgs } from "node:util";
+import { HOOKS_OPTIONS, HOOKS_USAGE } from "../../src/usage.ts";
+
+/** The hooks, as the app's folder sees them once @lernapps/tooling is installed. */
+export const HOOKS_DIR = "node_modules/@lernapps/tooling/archetypes/shared/hooks";
+/** Where git runs them from: a folder npm leaves alone when it replaces the package. */
+export const GIT_HOOKS_DIR = "node_modules/.cache/lernapps/hooks";
+const HOOKS = ["pre-commit", "pre-push"] as const;
+
+export function installHooks(args: string[]): number {
+  const { values } = parseArgs({ args, options: HOOKS_OPTIONS, strict: true, allowPositionals: false });
+  if (values.help) {
+    process.stdout.write(HOOKS_USAGE);
+    return 0;
+  }
+  const say = (message: string) => process.stdout.write(`lernapps hooks: ${message}\n`);
+  const prefix = spawnSync("git", ["rev-parse", "--show-prefix"], { encoding: "utf8" });
+  if (prefix.error || prefix.status !== 0) {
+    say("not in a git repository, no hooks installed (git init, then npm install again)");
+    return 0;
+  }
+  const inside = prefix.stdout.trim();
+  if (inside !== "") {
+    say(`this folder is ${inside} inside another git repository; its hooks stay as they are`);
+    return 0;
+  }
+  // a missing hook of the package fails the commit or push: sh cannot read the file
+  mkdirSync(GIT_HOOKS_DIR, { recursive: true });
+  for (const hook of HOOKS) {
+    writeFileSync(
+      join(GIT_HOOKS_DIR, hook),
+      `# Written by lernapps hooks: runs the ${hook} hook of the installed @lernapps/tooling.\n. ./${HOOKS_DIR}/${hook}\n`,
+    );
+  }
+  // an app installed before the hooks had their own folder: vp config leaves any other core.hooksPath as it is
+  const current = spawnSync("git", ["config", "--local", "core.hooksPath"], { encoding: "utf8" });
+  if (current.stdout.trim() === `${HOOKS_DIR}/_`) {
+    spawnSync("git", ["config", "--local", "core.hooksPath", `${GIT_HOOKS_DIR}/_`]);
+  }
+  // the app's toolchain first, as npm puts it on the PATH of the prepare script
+  const env = {
+    ...process.env,
+    PATH: [join(process.cwd(), "node_modules", ".bin"), process.env["PATH"] ?? ""].join(delimiter),
+  };
+  const result = spawnSync("vp", ["config", "--no-agent", "--hooks-dir", GIT_HOOKS_DIR], { stdio: "inherit", env });
+  if (result.error) {
+    process.stderr.write(`lernapps hooks: cannot run vp: ${result.error.message}. Install the dependencies (npm ci)\n`);
+    return 1;
+  }
+  return result.status ?? 1;
+}

package/archetypes/shared/playwright.ts

@@ -0,0 +1,54 @@
+// The Playwright configuration of a lernapps app (@lernapps/tooling/playwright): end-to-end tests in e2e/*.e2e.ts
+// against the built app, served by `vp preview` on a free port, in Chromium at desktop width and at 360 px. An app's
+// playwright.config.ts is
+//
+//   export { default } from "@lernapps/tooling/playwright";
+//
+// or `export default playwright({ ... })` with its own settings over these. `lernapps check --pre-push` runs them.
+import { createServer } from "node:net";
+import { defineConfig, devices, type PlaywrightTestConfig } from "playwright/test";
+
+/** A port nobody listens on now, so that several apps (or test runs) can check at the same time. */
+const freePort = () =>
+  new Promise<number>((resolve, reject) => {
+    const server = createServer();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      server.close(() => resolve(typeof address === "object" && address !== null ? address.port : 4317));
+    });
+  });
+
+// Chosen once, when Playwright loads this configuration; its workers inherit the variable and load the same port.
+const PORT = (process.env["LERNAPPS_PREVIEW_PORT"] ??= String(await freePort()));
+const URL = `http://127.0.0.1:${PORT}/`;
+
+const base: PlaywrightTestConfig = {
+  testDir: "e2e",
+  testMatch: "*.e2e.ts",
+  forbidOnly: true,
+  // Every test opens its own page and depends on no other: they run in parallel, not one file after another, on
+  // three quarters of the machine's cores; the rest serves the app (vp preview). LERNAPPS_PLAYWRIGHT_WORKERS sets
+  // another number of workers: the tooling's own tests set 1, because they run many apps' checks at the same time.
+  fullyParallel: true,
+  workers: Number(process.env["LERNAPPS_PLAYWRIGHT_WORKERS"]) || "75%",
+  reporter: [["line"]],
+  // LERNAPPS_CHROMIUM: an installed Chromium that lernapps check starts where Playwright's own is missing
+  // (check/visit.ts)
+  use: {
+    baseURL: URL,
+    ...(process.env["LERNAPPS_CHROMIUM"]
+      ? { launchOptions: { executablePath: process.env["LERNAPPS_CHROMIUM"] } }
+      : {}),
+  },
+  projects: [
+    { name: "desktop", use: { ...devices["Desktop Chrome"] } },
+    { name: "360px", use: { ...devices["Desktop Chrome"], viewport: { width: 360, height: 740 } } },
+  ],
+  webServer: { command: `vp preview --host 127.0.0.1 --port ${PORT} --strictPort`, url: URL },
+};
+
+/** The configuration, with the app's own settings over it. */
+export const playwright = (config: PlaywrightTestConfig = {}) => defineConfig(base, config);
+
+export default playwright();

package/archetypes/shared/preset.ts

@@ -0,0 +1,81 @@
+// The shared base of the archetype presets (docs/arc42 ch. 5, "Archetype presets"): the vite-plus configuration an
+// app extends and never edits. Its vite.config.ts is
+//
+//   import { lernapps } from "@lernapps/tooling/preset";
+//   export default lernapps();
+//
+// with the app's own settings, if any, as the argument (merged over the preset). It sets lint (the lernapps lint
+// plugin and the severity of each of its rules, type-aware with type check, no `any`), format, unit tests, the
+// staged files of the pre-commit hook, and a build with relative URLs, so the app works under any path.
+import { defineConfig, mergeConfig, type UserConfig } from "vite-plus";
+
+/** Not code: what tools write, and prose. */
+const notCode = ["dist/**", "node_modules/**", "playwright-report/**", "test-results/**", "**/*.md"];
+
+/** The severity of each rule of the lint plugin (lint/rules/<id>.ts), as `lernapps/<id>`. */
+const lernappsRules = {
+  "lernapps/learner-text-german": "error",
+  "lernapps/no-request-before-click": "error",
+  "lernapps/storage-through-wrapper": "error",
+  "lernapps/suppression-reason": "error",
+  "lernapps/vue-component-browser-globals": "error",
+  "lernapps/vue-component-imports": "error",
+  "lernapps/vue-component-no-html-injection": "error",
+  "lernapps/vue-component-no-network": "error",
+} as const;
+
+const preset: UserConfig = {
+  base: "./",
+  fmt: {
+    printWidth: 120,
+    ignorePatterns: notCode,
+  },
+  lint: {
+    ignorePatterns: notCode,
+    jsPlugins: ["@lernapps/tooling/lint"],
+    options: {
+      typeAware: true,
+      typeCheck: true,
+    },
+    rules: {
+      ...lernappsRules,
+      "typescript/no-explicit-any": "error",
+    },
+  },
+  test: {
+    include: ["src/**/*.test.ts", "test/**/*.test.ts"],
+  },
+  staged: {
+    // Formats the staged files before the hook runs the fast part of `lernapps check`, which lints and type-checks the
+    // whole app once: `vp check --fix` here would type-check the staged files a second time.
+    "*.{ts,tsx,json}": "vp fmt",
+  },
+};
+
+/** Whether the plugins (nested lists, as Vite takes them) hold one named `name`. */
+const hasPlugin = (plugins: unknown, name: string): boolean =>
+  Array.isArray(plugins)
+    ? plugins.some((plugin) => hasPlugin(plugin, name))
+    : typeof plugins === "object" && plugins !== null && "name" in plugins && plugins.name === name;
+
+/**
+ * The preset, with the app's own settings merged over it. With the interactive runtime's build step among the
+ * plugins, a component may also import the app's own files in src/ and the libraries in its dependencies, as that
+ * build allows (lint/rules/vue-component-imports.ts).
+ */
+export const lernapps = (config: UserConfig = {}): UserConfig => {
+  const interactive = hasPlugin(config.plugins, "lernapps-interactive");
+  // set in place, not merged: mergeConfig would concatenate the rule's severity with its options
+  const base: UserConfig = interactive
+    ? {
+        ...preset,
+        lint: {
+          ...preset.lint,
+          rules: { ...preset.lint?.rules, "lernapps/vue-component-imports": ["error", { scope: "src" }] },
+        },
+      }
+    : preset;
+  return defineConfig(mergeConfig(base, config));
+};
+
+export default lernapps();

package/archetypes/shared/storage.ts

@@ -0,0 +1,167 @@
+// The only storage of a lernapps app (@lernapps/tooling/storage; lint rule storage-through-wrapper): on the device,
+// in localStorage, under the app's own prefix, because every app on lernapps.net shares one origin. That origin's
+// localStorage is small (about 5 MB in most browsers) and shared, so an app keeps at most STORAGE_QUOTA under its
+// prefix: a save beyond it is refused. The learner's settings for every app or every app of an archetype are kept
+// under SETTINGS_PREFIX, which every app shares, within SETTINGS_QUOTA (createSettings). Every access is wrapped in try/catch: when the browser blocks storage, it is
+// full or the app's quota is used up, the app keeps working and remembers nothing more. What should last only while the
+// tab is open, such as an answer being written, which a reload must not lose but a new day need not keep, goes into
+// sessionStorage instead ({ type: "sessionStorage" }), with the same prefix and quota.
+
+/**
+ * What an app may keep under its prefix: 100 kB (100,000 bytes), measured as browsers count localStorage, 2 bytes per
+ * UTF-16 code unit of every key (with the prefix) and value.
+ */
+export const STORAGE_QUOTA = 100_000;
+
+/** What an app keeps on the device: JSON values under its own keys. */
+export interface DeviceStorage {
+  /** The value saved under `key`, if there is one and `guard` accepts it. */
+  load<T>(key: string, guard: (value: unknown) => value is T): T | undefined;
+  /**
+   * Saves a JSON value; false when the browser does not let the app store it, or when the app's values would then
+   * take more than STORAGE_QUOTA. A refused save keeps the value saved before.
+   */
+  save(key: string, value: unknown): boolean;
+  /** Removes the value saved under `key`. */
+  remove(key: string): void;
+}
+
+/** Where the values are kept: until removed (localStorage, the default), or while the tab is open (sessionStorage). */
+export type StorageType = "localStorage" | "sessionStorage";
+
+export interface StorageOptions {
+  type?: StorageType;
+}
+
+/**
+ * The storage of the app named `app`: its id in the catalog (entries/<id>.yaml, rule own-data-only), e.g. "brueche";
+ * in localStorage, or with `type: "sessionStorage"` in sessionStorage, which the browser empties when the tab closes.
+ */
+export function createStorage(app: string, options: StorageOptions = {}): DeviceStorage {
+  return prefixed(`lernapps:${app}:`, `lernapps:${app}:`, STORAGE_QUOTA, options.type);
+}
+
+/**
+ * The values under `prefix` in the browser's storage `type`, which may take at most `quota` bytes together with every
+ * other value under `counted` there.
+ */
+function prefixed(prefix: string, counted: string, quota: number, type: StorageType = "localStorage"): DeviceStorage {
+  /** The bytes the values under `counted` take, without the one under `except`. */
+  const used = (target: Storage, except: string): number => {
+    let bytes = 0;
+    for (let i = 0; i < target.length; i++) {
+      const key = target.key(i);
+      if (key === null || key === except || !key.startsWith(counted)) continue;
+      bytes += (key.length + (target.getItem(key)?.length ?? 0)) * 2;
+    }
+    return bytes;
+  };
+  const store = (): Storage | undefined => {
+    try {
+      return globalThis[type];
+    } catch {
+      return undefined;
+    }
+  };
+  return {
+    load(key, guard) {
+      try {
+        const text = store()?.getItem(prefix + key);
+        if (text === null || text === undefined) return undefined;
+        const value: unknown = JSON.parse(text);
+        return guard(value) ? value : undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    save(key, value) {
+      try {
+        const target = store();
+        if (!target) return false;
+        const text = String(JSON.stringify(value));
+        if (used(target, prefix + key) + (prefix.length + key.length + text.length) * 2 > quota) return false;
+        target.setItem(prefix + key, text);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    remove(key) {
+      try {
+        store()?.removeItem(prefix + key);
+      } catch {
+        // nothing stored, nothing to remove
+      }
+    },
+  };
+}
+
+/**
+ * What the learner's settings for every app and for every app of an archetype take together under SETTINGS_PREFIX:
+ * 10 kB (10,000 bytes), counted as STORAGE_QUOTA is. A setting for one app only counts towards that app's quota.
+ */
+export const SETTINGS_QUOTA = 10_000;
+
+/**
+ * Where the learner's settings for more than one app are kept: `lernapps:settings:<key>` for every app,
+ * `lernapps:settings:<archetype>:<key>` for every app of an archetype. `settings` is never the id of an app.
+ */
+export const SETTINGS_PREFIX = "lernapps:settings:";
+
+/** Where a setting holds: for this app only, for every app of its archetype, or for every app. */
+export type SettingScope = "app" | "archetype" | "all";
+
+/** The learner's settings as one app sees them (`createSettings`). */
+export interface Settings {
+  /** The setting under `key` that holds for this app, the most specific one, with where it holds. */
+  load<T>(key: string, guard: (value: unknown) => value is T): { value: T; scope: SettingScope } | undefined;
+  /**
+   * Saves a setting where it holds and removes the more specific ones this app would read first, so that it takes
+   * effect here too (for every app also the archetype's, which other apps of the archetype then lose); false when the browser does not let the app store it, the quota is used up, the app has no archetype
+   * for `archetype`, or `key` has a colon. A refused save changes nothing.
+   */
+  save(key: string, value: unknown, scope: SettingScope): boolean;
+  /** Removes the setting under `key` where it holds; one that is more general may then hold. */
+  remove(key: string, scope: SettingScope): void;
+}
+
+/**
+ * The learner's settings for the app named `app` (its id, as for `createStorage`) of the archetype `archetype`
+ * (`explainer`, as its pages mark it with `<meta name="lernapps-archetype">`): the app's own one under
+ * `lernapps:<app>:settings:<key>` goes before the archetype's, which goes before the one for every app
+ * (rule own-data-only lets an app touch these and no other archetype's). A key has no colon, so that a key for every
+ * app is never taken for an archetype's.
+ */
+export function createSettings(app: string, archetype?: string): Settings {
+  const stores: [SettingScope, DeviceStorage | undefined][] = [
+    ["app", prefixed(`lernapps:${app}:settings:`, `lernapps:${app}:`, STORAGE_QUOTA)],
+    [
+      "archetype",
+      archetype === undefined
+        ? undefined
+        : prefixed(`${SETTINGS_PREFIX}${archetype}:`, SETTINGS_PREFIX, SETTINGS_QUOTA),
+    ],
+    ["all", prefixed(SETTINGS_PREFIX, SETTINGS_PREFIX, SETTINGS_QUOTA)],
+  ];
+  const valid = (key: string) => key !== "" && !key.includes(":");
+  return {
+    load(key, guard) {
+      if (!valid(key)) return undefined;
+      for (const [scope, store] of stores) {
+        const value = store?.load(key, guard);
+        if (value !== undefined) return { value, scope };
+      }
+      return undefined;
+    },
+    save(key, value, scope) {
+      const at = stores.findIndex(([where]) => where === scope);
+      const store = stores[at]?.[1];
+      if (!valid(key) || store === undefined || !store.save(key, value)) return false;
+      for (const [, narrower] of stores.slice(0, at)) narrower?.remove(key);
+      return true;
+    },
+    remove(key, scope) {
+      if (valid(key)) stores.find(([where]) => where === scope)?.[1]?.remove(key);
+    },
+  };
+}

package/archetypes/shared/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "lib": ["es2023", "dom", "dom.iterable"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "types": ["vite-plus/client"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "useUnknownInCatchVariables": true,
+    "allowJs": false,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true
+  }
+}