Typen, IntelliSense und Beispiele

@voice/review stellt Befunde dar, die deine einbindende Anwendung liefert. Der ESM-Einstiegspunkt enthält TypeScript-Deklarationen und JSDoc für Vervollständigung, abgeleitete Callback-Typen und Hover-Hilfe. JavaScript kann // @ts-check nutzen; klassische Skripte können Typen für das Global VoiceReview referenzieren. Analyse und Quellbearbeitung liegen bei der einbindenden Anwendung, außerhalb dieser Library-API.

Build und Editor einrichten#

In diesem Arbeitsverzeichnis:

npm run build -w @voice/review
npm run test:types -w @voice/review

Löse Importe über den Paketnamen @voice/review auf, nicht über einen privaten src/-Pfad. Die Einträge exports und types des Pakets verweisen auf erzeugte Deklarationen. Baue das lokale Paket, bevor du es in einem anderen Projekt verwendest. Der Test für einbindende Anwendungen prüft die Modulauflösung mit NodeNext und Bundler.

In JavaScript-Projekten aktiviert // @ts-check die Prüfung der aktuellen Datei. Alternativ kann ein Projekt allowJs, checkJs, strict und noEmit in seiner TypeScript-Konfiguration setzen. Nimm die DOM-Library auf, wenn du die standardmäßige lib-Liste ersetzt. Ein Editor mit TypeScript Language Service kann Controller-Methoden, Callback-Parameter, Literaloptionen wie encoding: 'utf16', Methodensignaturen und die öffentlichen JSDoc-Texte anzeigen.

TypeScript: einbinden, aktualisieren, freigeben#

Dieses vollständige Beispiel verwendet einen exakten Klartext-Quellstring. Die Beispielanwendung erzeugt ihr eigenes Markup; die Annotations-Library lässt dieses Markup unverändert. Beziehe bei HTML-, Markdown- oder Framework-Inhaltsdateien die Einheiten und Quellbereiche aus einem Quelladapter, statt Dateioffsets aus gerendertem HTML abzuleiten.

import {
  mountVoiceReview, codePointOffsetToUtf16,
  type Finding, type SourceSpan, type TextUnit,
} from '@voice/review';

export function showReview(root: HTMLElement): () => void {
  const source = '🧭 Clear copy.';
  const sourceSpan: SourceSpan = {
    start: 0, end: source.length, encoding: 'utf16',
  };
  const unit: TextUnit = {
    id: 'intro', text: source, sourceSpan,
    kind: 'paragraph', language: 'en',
  };
  const finding: Finding = {
    id: 'example-1', ruleId: 'host.example', category: 'wording', severity: 'info',
    message: 'Example finding', explanation: 'Supplied example data; no analysis is run.',
    quote: 'Clear', unitId: unit.id,
    start: codePointOffsetToUtf16(source, 2),
    end: codePointOffsetToUtf16(source, 7),
    suggestion: null, engine: 'host/example',
  };
  const paragraph = root.ownerDocument.createElement('p');
  paragraph.dataset.voiceUnit = unit.id;
  paragraph.textContent = source;
  root.replaceChildren(paragraph);

  const review = mountVoiceReview({
    root, units: [unit], findings: [finding], feedback: [],
    onSelect(selection) {
      // selection is inferred: unitId, quote, start and end.
      console.info(selection.quote);
    },
  });
  review.update({ findings: [finding] });
  console.info(review.getDiagnostics());
  return () => review.dispose();
}

Rufe die zurückgegebene Aufräumfunktion auf, wenn die einbindende Anwendung die Route wechselt, die Ansicht entfernt oder ihr iframe ersetzt. Rufe mountVoiceReview auf, nachdem das Zieldokument geladen wurde. Ein neuer Wurzelknoten benötigt eine neue Einbindung; update() ändert Daten und Callbacks am bestehenden Wurzelknoten. Das geprüfte Beispiel steht in typescript.ts.

JavaScript: dieselbe API mit JSDoc#

// @ts-check
import { mountVoiceReview } from '@voice/review';

/**
 * @param {HTMLElement} root
 * @param {readonly import('@voice/review').TextUnit[]} units
 * @param {readonly import('@voice/review').Finding[]} findings
 * @returns {() => void}
 */
export function showReview(root, units, findings) {
  const review = mountVoiceReview({
    root, units, findings, feedback: [],
    onSelect(selection) { console.info(selection.quote); },
  });
  return () => review.dispose();
}

Die Typen des Callbacks und des zurückgegebenen Controllers werden abgeleitet, ohne diese Datei in TypeScript umzuwandeln. Ein vollständiges Beispiel mit Quellbereichen steht in javascript.js.

Ein klassisches Skript ohne Bundler#

Lade den gebauten Laufzeitcode als gewöhnliches Skript und danach deine Integration:

<script src="/library/voice-review.js"></script>
<script src="/review-host.js"></script>

Am Anfang von review-host.js, wenn @voice/review für den Editor verfügbar ist:

/// <reference types="@voice/review/standalone" />
// @ts-check
const connection = VoiceReview.connectVoiceStudio({
  studioOrigin: 'http://127.0.0.1:5188',
});
window.addEventListener('pagehide', () => connection.dispose(), { once: true });

Die Referenz mit drei Schrägstrichen liefert nur Deklarationen. Sie lädt die Library weder herunter noch führt sie sie aus. Importiere den eigenständigen Laufzeitcode nicht als ESM-Modul, um ein Global zu erhalten: ESM verwendet benannte Importe aus @voice/review. Das geprüfte Global-Beispiel steht in standalone.js.

Koordinaten und KI-Integration#

SourceSpan.start/end beziehen sich auf die ursprüngliche Quelldatei. start/end eines Befunds oder einer Auswahl beziehen sich auf den Text der zugeordneten Einheit. Beide zählen UTF-16-Codeeinheiten ab null in halboffenen Intervallen. Ein Emoji kann zwei Codeeinheiten belegen. Im Klartextbeispiel liegt Clear in UTF-16 bei [3, 8), während eine Codepoint-Engine [2, 7) meldet. Rechne beide Endpunkte mit codePointOffsetToUtf16 um, bevor du solche Befunde an diese Library übergibst. Passende Koordinaten allein stellen noch keine Zuordnung zur Quelldatei her: Markup, Entities und ausgeschlossene Inhalte erfordern einen Adapter.

Eine einbindende Anwendung kann validierte KI-Befunde genauso an mountVoiceReview oder update übergeben wie Befunde lokaler Regeln. Sie muss das Schema der Engine, die Offset-Kodierung, das exakte Zitat, die Identität der Einheit und die Quellversion prüfen. Sie verantwortet Ziel, Marketingkontext, Modellroute, Aufgabenausführung, Herkunft der Ergebnisse und Review-Entscheidungen. Die Bridge transportiert bereitgestellte Review-Daten zu einer ausdrücklich integrierten Live-Seite; sie überträgt keine Backend-Zugangsdaten und startet keine Modellarbeit.

Nutze createReviewClient ausschließlich in der autorisierten einbindenden Anwendung, wenn Feedback über das Studio-Backend gespeichert werden soll. Der Client bietet typisierte Operationen getDocument und saveFeedback. Stelle den aktuellen Bearer-Token über einen von der Anwendung verwalteten Getter im Arbeitsspeicher bereit. Bette ihn niemals in die geprüfte Website, URLs, Versionsverwaltung oder Berichte ein. FeedbackInput enthält expectedVersion, expectedReviewRevision und eine requestId. Behalte bei der Wiederholung eines Speichervorgangs mit ungewissem Ausgang dieselbe Anfrage-ID und die exakte Nutzlast bei. Das Anwenden auf die Quelle bleibt ein eigener, abgesicherter Backend-Ablauf. Das Overlay allein besitzt weder einen dauerhaften Feedback-Speicher noch eine Operation zum Schreiben der Quelle.

Das Library-README enthält Beispiele zum Speichern; der Bridge-Vertrag beschreibt Origin- und Sitzungsprüfungen.

Was die Prüfungen nachweisen#

packages/review/test/types.test.mjs erstellt außerhalb dieses Arbeitsverzeichnisses eine isolierte einbindende Anwendung, die ausschließlich die deklarierten Auslieferungsdateien des Pakets nutzt. Der Test kompiliert echte TypeScript-, checkJs- und klassische Global-Beispiele sowie absichtlich ungültige Beispieldateien mit NodeNext- und Bundler-Auflösung. Erwartete Fehler stellen sicher, dass Anforderungen an Kodierung, Wurzelknoten, Kategorie und Callbacks nicht unbemerkt zu any abgeschwächt wurden.

Der Test ruft außerdem den tatsächlichen TypeScript Language Service auf: für Vervollständigung von Controller und Auswahl, Vervollständigung des klassischen Globals, Signaturen der Aufräumfunktionen und JSDoc-Hover-Texte. Damit werden die Metadaten geprüft, die kompatible Editoren verwenden. Der Test bedient weder die VS-Code-Oberfläche noch weist er das Verhalten einer bestimmten Editor-Erweiterung oder die Darstellung im eingebetteten Browser von VS Code nach. Bestehende Laufzeittests der Library prüfen Einbindung, Aktualisierungen, Freigabe, Verankerung und Bridge-Verhalten gesondert.