DocsDownload
Menu

The plan and its versions

On this page

The plan as a working copy, the versions a person freezes, what changed between them, and the plan’s document. Part of the architecture, the contract every change follows.

Versions (D52)

plan.json is always the working copy; plan-versions/V<n>.json its versions, frozen copies made by a person (their number, day, content hash and plan never change; their sends and their validation are added), and plan-versions/notes.json the author’s notes for the client on the changes in no version yet. loadProject reads them into Project.planVersions and Project.planNotes; no package carries them, archives and backups do.

  • State and references (@elabora/core project/plan-versions.ts): usableVersions (those whose plan gives their hash), planState (draft without a validated version, approved when the working copy is the latest validated version, modified otherwise), planVersionsView (every version made, sent and validated; the two references of the app: the changes since the latest validated version, its marks, and those in no version yet, its pill’s count; what an export shows by default and how many changes it would not show; the verbatim texts changed since the validation), planDiffBetween(project, { from, to }), notesFor, describePlanVersions (a line for agents and the command line).
  • The diff (project/plan-diff.ts planDiff(base, current, course?)): elements of two plans matched by their ids (objectives, items, texts and questions wherever they are, sources, and the plan’s own fields), each added, removed or changed, moved (from its position: the elements around it that kept their order did not move, the longest common subsequence), an item’s part changed (the part it belongs to, effectiveParts in project/plan-order.ts: its own, else the one before it, and in a plan without parts the title of its section in the course, planCourse(project), which every caller with a project gives; an item whose part was only written down, from none to the part it was in, did not change part, so a drag counts once; a base with no parts and no course has none to compare), each field changed with its texts word by word (diffRich), verbatim for a text the base kept « à l’identique ». Every change has a key (item:ITEM-3) that notes and revertPlanChange (« Revenir à la V2 ») use.
  • Rules (validate/plan.ts, validate/structure.ts): W_PLAN_DRAFT, E_PLAN_NOT_APPROVED for release builds without a validated version, W_PLAN_MODIFIED_SINCE_VALIDATION, W_PLAN_VERBATIM_CHANGED, E_PLAN_VERSION_INVALID. The build report’s plan.validated and plan.changesSince, and the proof dossier, say the version a release is built against and the changes delivered since.

The plan’s document (D48, D52)

What the client reads, comments and signs: one version of the plan, the latest by default, or its working copy, as one document: its properties at its head (status, version, validated by, the module’s duration and delivery, the history of the versions up to it) and six sections (framing, objectives, sequence, validated texts, assessments, sources), in the module’s language (French, else English).

  • The model (@elabora/core plan-document/model.ts planDocument(project, { date, version }), format elabora/plan-document/2; planDocumentTarget says what a version option shows): data without layout, read by every renderer (the exports, the app’s Document view, later a review link that shows the plan alone). Its texts are the plan’s Markdown and the same as rich-text data (plan-document/rich.ts: paragraphs, lists, tables, quotes, code, maths, with marks), so no renderer parses Markdown. What changed since the latest validated version up to the one shown reads in place: a changed text as one text whose words are marked deleted or inserted (diffRich, diffPlain for titles), an element added (all inserted) or removed (in its old place, all deleted), each with its mark (« Modifié · déplacé, c’était le point 4 ») and the author’s note for the client. It never says who wrote the plan or a change.
  • HTML (plan-document/html.ts): one page, its sections in <details> that fold on screen; an element changed is marked in the margin’s blue, a verbatim text changed in amber, the notes for the client in the margin on a wide screen and under their element in print; an @page rule gives A4, margins and a footer (the title, « Page n / N »), so a print needs no header or footer template. @elabora/node plan-document.ts adds the fonts inline (Inter and JetBrains Mono from @elabora/fonts, WOFF2 data URIs): the same page prints the same everywhere.
  • PDF: that page printed by Chromium: with PLAN_PDF_ELECTRON by Electron’s webContents.printToPDF in an offscreen window of PLAN_PDF_WINDOW (the app, and the command line when the app is installed: printPlanDocument through a browser worker, emulator/electron.ts printWithElectron, since Electron’s DevTools protocol has no Page.printToPDF), else with PLAN_PDF_PLAYWRIGHT by Chrome, Edge or Playwright’s Chromium: tagged, with an outline from the headings; finishPlanPdf sets its dates to the document’s day, so the same Chromium gives the same bytes (the app’s and the command line’s files are the same).
  • Word (plan-document/docx.ts, omml.ts): WordprocessingML written by hand, zipped by createZip (D8). Word’s own styles (Title, Heading 1 to 3) and named styles of its own (Elabora …), no direct formatting but the plan’s own emphasis; tables for the properties and the plan’s own tables only; maths as Word equations (OMML, from temml’s MathML); the changes since the validated version as tracked changes (author « Depuis la V2 validée », no date), the notes for the client as comments (word/comments.xml, author « Note pour le client ») on the range of their element; a bookmark around every objective, item, validated text, question and source, wordBookmarkName(id) (el_ then the id, « - » as « _ », « _ » as « _u »), read back by planIdOfBookmark.
  • Where. elabora plan export [dir] [--version Vn|current] [--format pdf|docx|html] [--out] [--date] (default dist/<course id>-plan.<format>), MCP elabora_export_plan_document { format, version }, @elabora/node/plan-document exportPlanDocument (which records the send on the version it shows, one change: record_plan_send), writePlanDocument (the file only: the engine records the send through its queue), readPlanDocument, planDocumentPage, planDocumentWord, printPlanDocument, and the engine’s requests above. Exporting never makes a version.