Satzstrom

Das Satzstrom-Modell in einer Seite.

Ein Dokument ist ein normales React-Modul. Nur physische Seiten, wiederkehrende Rahmen und berechnete Dokumentstruktur brauchen eigene Primitives.

document.tsx
import {
  Document,
  Page,
  PageMaster,
  type PageLayoutProps,
} from "@satzstrom/primitives";

function ReportPage({ children, page, pages }: PageLayoutProps) {
  return (
    <div className="report-page">
      <header>Jahresbericht</header>
      <main>{children}</main>
      <footer>{page} / {pages}</footer>
    </div>
  );
}

export default function Report() {
  return (
    <Document title="Jahresbericht" lang="de">
      <Page size="A4" className="cover">2026</Page>
      <PageMaster layout={ReportPage} size="A4">
        <h1>Einleitung</h1>
        <p>Dieser Inhalt fließt über alle nötigen Seiten.</p>
      </PageMaster>
    </Document>
  );
}

Das Seitenmodell.

Page gestaltet genau eine Seite. PageMaster lässt Inhalte durch einen React-Rahmen fließen; mehrere Systeme dürfen im selben Document aufeinanderfolgen.

Document
Der einzige Root. title und lang gehören hierhin; author, subject, keywords und dir sind optional.
Page
Ideal für Cover, Trenner und bewusst komponierte Einzelblätter.
PageMaster
Sein layout rendert children genau einmal und erhält globale page- und pages-Werte.
CSS
Millimeter für physische Grenzen, flexible Layouts im Satzspiegel und normale Styles für Komponenten.

Daten sind ein normaler Prop.

Ohne externe Daten genügt der Default-Export. Existiert data.json, exportiert das Modul zusätzlich ein benanntes Zod-schema; der validierte Wert kommt als einzelner data-Prop an.

Das Schema darf Objekte, Arrays, Primitive oder Unions beschreiben. Ohne Schema wird eine benachbarte Datendatei bewusst als Fehler behandelt, nicht still ignoriert.

Daten validieren
import { z } from "zod";
import { Document, Page } from "@satzstrom/primitives";

export const schema = z.object({
  title: z.string(),
  total: z.number(),
});

type Data = z.infer<typeof schema>;

export default function Report({ data }: { data: Data }) {
  return (
    <Document title={data.title} lang="de">
      <Page>{data.total}</Page>
    </Document>
  );
}

Die öffentlichen Primitives.

Das Paket bleibt bewusst klein. Alles Visuelle — Abbildungen, Tabellen, Karten, Kapitel oder ein vollständiges Designsystem — baust du als normale Komponenten.

Document
Wurzel, Sprache und PDF-Metadaten.
Page
Eine frei gestaltete physische Seite.
PageMaster
Fließender Inhalt in einem wiederkehrenden React-Seitenrahmen.
PageBreak
Erzwingt innerhalb eines PageMaster einen neuen Seitenbeginn.
RepeatBox
Wiederholt Box-Dekoration auf jedem Fragment.
defineSequence
Definiert ein unabhängiges Nummerierungssystem.
Sequence
Registriert nummerierte, verschachtelte Inhalte.
Contents
Erzeugt ein Inhaltsverzeichnis mit endgültigen Seiten.
Ref
Referenziert Nummer, Titel oder Seite einer HTML-ID.
Footnote
Setzt nummerierte Fußnoten in den Seitenfuß.
Math
Rendert KaTeX als HTML und MathML.
useRenderReady
Synchronisiert asynchrone Browser-Inhalte mit der Messung.

Die CLI.

Die Befehle akzeptieren document.tsx oder seinen Ordner. Ohne Argument gelten document.tsx und data.json im aktuellen Ordner als Konvention. Explizite Pfade haben Vorrang.

init <ordner>
Erstellt und installiert ein eigenständiges Starterprojekt.
add <name>
Ergänzt ein Dokument sicher in einem bestehenden TypeScript-Projekt.
dev [document]
Startet die lokale Preview mit Reload, Zoom, Thumbnails und Diagnosen.
check [document]
Prüft Daten und Layout; --strict macht Warnungen zu Fehlern.
render [document]
Schreibt das PDF, optional als PDF/A-2a und PDF/UA-1.
page 3 [document]
Schreibt eine deterministische Seite als PNG, optional mit Debug-Markierungen.
inspect [document]
Liefert Seiten, Formate, Diagnosen, Layout-Passes und Revision als JSON.
mcp
Startet den lokalen stdio-Server für Agenten.
doctor
Prüft Node, Chromium und PDF-Laufzeit.

Ein verlässlicher Abschluss.

Der normale Authoring-Loop bleibt kurz. Debug-Werkzeuge kommen nur dann dazu, wenn eine Seitenkante oder Fragmentierung erklärt werden muss.

Gezielt untersuchen
satzstrom inspect --json
satzstrom page 3 --debug
  • Revision

    Quellen, CSS, Daten und lokale Assets bilden gemeinsam eine inhaltsbasierte Dokumentrevision.

  • Strict

    Layoutwarnungen stoppen den Build, bevor eine problematische PDF ausgeliefert wird.

  • Final

    satzstrom render --out bericht.pdf --strict schreibt den stabilen Stand.