Skip to content

docs: describe the browser emulation across the normative documents - #343

Merged
ttbombadil merged 4 commits into
feature/browser-emulationfrom
docs/release-readiness
Oct 24, 2026
Merged

ttbombadil merged 4 commits into
feature/browser-emulationfrom
docs/release-readiness

Conversation

@ttbombadil

Copy link
Copy Markdown
Collaborator

Worum es geht

Konsistenzprüfung der Dokumentation gegen Plan-Abschnitt 8 und den umgesetzten Stand; dazu die Vorbereitung dessen, was nur ein Mensch tun kann.

Normative Dokumente

  • ARCHITECTURE: Die Governance-Grenzen sagten, das Dokument beschreibe „den Host-Mock als einzige Laufzeit“, spätere Abschnitte aber schon die Emulation. Jetzt beschreibt es den umgesetzten Stand (ADRs weiter Proposed): Datenfluss mit Worker und Compile-Sandbox, Komponenten Emulationskern und Board-Katalog, Client-Laufzeiten, Compile- und Simulation-Flow für beide Laufzeiten, State Ownership, Browser-Laufzeit in der Sicherheit, Metriken und Readiness, Worker-Protokoll, ATtiny85 im Rückfall.
  • SECURITY: neuer Abschnitt „Browser runtime boundary“ (geprüft gegen den Code: SHA-256 und Größe beim Laden, runId, 1–300 s, Eingabe 4 KiB/1 MiB, Fristen); Profile und Sandbox-Abschnitt auf Host-Mock bzw. Compile-Sandbox eingegrenzt; Produktions-Checkliste mit drei Images.
  • RELEASE_RUNBOOK 1.1.0: Vorabversionen aus dem Integrationsbranch, Ablauf mit Befehlen, Abnahmekriterien für v2.0.0, release/v1.x (fehlte ganz, Plan P7.3).
  • CHANGELOG „Unreleased“: vollständig. Die Verhaltensänderungen für Lehrende, die Plan 9.2 verlangt, Betreiberhinweise (drei Images, neue Variablen, Pilot, Rückkehr), Neues, Behobenes. Korrigiert: Er nannte die Einbettungs-API noch 1.4.0.
  • README: Boards, Tech-Stack, ATTinyCore, Skripte, Architekturkurzfassung mit Browser-Emulation und Compile-Sandbox.
  • EXTERNAL_API: ATtiny85 (Pins, Software-UART, board), neuer Abschnitt zum Verhalten bei Verbindungsverlust (fehlte, Plan P4.7).
  • ssot_agent_policy: Git-Flow des Integrationsbranchs (fehlte, Plan P0.7). SSOT SerialOutput: Software-UART des ATtiny85.
  • USER_GUIDE: ATtiny85 bei Speicher und Empfangspuffer (32 Byte laut Core); „wie auf dem gewählten Board“.
  • OPEN_POINTS: offene Punkte aus Plan-Abschnitt 11 (EMU-*), AVR8JS-PATCHES, EDITOR-INDENT; D5 gilt nur für den Host-Mock.
  • INSTALL_SERVER, CAPACITY_*, docs/README: ATtiny85, Geltung der Simulationsmessungen nur für den Host-Mock, Index der neuen SSOTs.

Vorbereitung für Menschen (docs/proposals/human-tests.md)

  • Teil 4: Aufnahmen an Nano, Mega 2560 und ATtiny85 (Aufbau mit ISP-Programmer und DTR-Reset, Fuses, welche 9 Fälle das Werkzeug nicht übernehmen kann und warum).
  • Teil 5: Texte für vier Issues an avr8js (upstream geprüft: keine Duplikate).
  • Teil 6: fertiger Text für das README von UnoSim-Examples (Feld board; der Absatz über die Abweichungen beschrieb nur V1).
  • Teil 7: Schritte für v2.0.0-beta.1 (Entscheidungen, Tag-Befehl, Pilot).

Werkzeuge

  • record:hardware: --programmer und --upload-port für Boards ohne USB-Bootloader. Fehler behoben: Beim Übernehmen schrieb das Werkzeug immer arduino:avr@1.8.8 als Toolchain in case.json, auch für ATtiny85-Fälle (ATTinyCore). Neuer Test recordingToolchain.
  • check:docs prüft nur Markdown-Dateien, die Git kennt. Lokal ließen ignorierte Entwürfe (local-temp/) die Prüfung scheitern, in CI nicht. Weggefallen sind nur ignorierte Ausgaben (Tutor-Qualität, Kapazitätsläufe, local-temp); 91 statt 121 Dateien.

Abhängigkeiten

Der CHANGELOG nennt die Korrekturen aus #341 (Timer-1-PWM) und #342 (verborgener Tab); AVR8JS-PATCHES zählt die Korrektur aus #341 mit. Bitte nach diesen beiden mergen.

Prüfungen

npm run check:docs (91 Dateien), npm run check, npm run lint, tests/server/record-hardware-lib.test.ts (9), Pre-Push-Gate mit Sonar grün.

🤖 Generated with Claude Code

ttbombadil and others added 4 commits October 24, 2026 11:06
Plan section 8 lists the documents V2 changes. ARCHITECTURE still described the
host mock as the only runtime, SECURITY had no browser runtime boundary, the
release runbook no pre-releases from the integration branch, and the CHANGELOG
no boards, compile sandbox or behaviour changes for teaching. The docs check
reads only files Git tracks, so ignored drafts no longer fail it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Recording guide for Nano, Mega 2560 and ATtiny85 (with ISP programmer and
DTR reset), issue texts for the four avr8js defects the profile corrects, the
UnoSim-Examples README change and the steps of v2.0.0-beta.1. The recording
tool uploads through a programmer and names the ATTinyCore toolchain when it
accepts an ATtiny85 case.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ments

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ttbombadil
ttbombadil merged commit e00f909 into feature/browser-emulation Oct 24, 2026
6 checks passed
@ttbombadil
ttbombadil deleted the docs/release-readiness branch October 24, 2026 16:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant