@openpresentation/opf 0.7.0 → 0.9.0

package/dist/composition.d.ts

@@ -95,8 +95,12 @@ interface ComposedItem {
     value: unknown;
     payload: Record<string, unknown>;
     box: LayoutBox;
-    text?: TextFit | RichTextFit | ListFit;
+    text?: TextFit | RichTextFit | ListFit | CodeTextFit;
     textStyle?: TextStyle;
+    /** Complete accepted quote internals; consumers must reuse these fits and styles. */
+    quoteLayout?: QuoteLayout;
+    /** Complete accepted code internals, including source lines and literal tab positions. */
+    codeLayout?: CodeLayout;
     /** Effective container settings, including inherited readability constraints. */
     composition: Composition;
 }
@@ -121,6 +125,37 @@ interface ComposedFlow {
     itemCount: number;
     slotCount: number;
 }
+/** Additive penalties in grid-score-v3; lower is preferred. These are not quality percentages. */
+interface CompositionPenalties {
+    cellProportions: number;
+    fontReduction: number;
+    textOverflow: number;
+    tableOverflow: number;
+    smallCells: number;
+    emptySlots: number;
+}
+interface CompositionCandidate {
+    columns: number;
+    rows: number;
+    score: number;
+    penalties: CompositionPenalties;
+}
+interface CompositionDecision {
+    path: string;
+    mode: NonNullable<Composition['mode']> | 'regions';
+    reason: 'lowest-score' | 'configured-mode' | 'promoted-regions';
+    selectedColumns?: number;
+    /** Only candidates actually evaluated by automatic selection, in tie-break order. */
+    candidates: CompositionCandidate[];
+}
+interface CompositionExplanation {
+    algorithm: 'grid-score-v3';
+    /** Provided widths do not establish shaping, glyph coverage or native fidelity. */
+    textMeasurement: 'estimated' | 'provided';
+    decisions: CompositionDecision[];
+    /** Payloads whose complete internal fit is not covered by this scoring model. */
+    unmeasuredPayloads: string[];
+}
 interface SlideComposition {
     width: number;
     height: number;
@@ -130,6 +165,7 @@ interface SlideComposition {
     flows: ComposedFlow[];
     diagnostics: LayoutDiagnostic[];
     composition: Composition;
+    explanation?: CompositionExplanation;
 }
 interface ComposeSlideOptions {
     fonts?: Partial<FontFamilies>;
@@ -138,16 +174,134 @@ interface ComposeSlideOptions {
     height?: number;
     slideIndex?: number;
     layout?: Record<string, unknown>;
+    /** Return candidate scores and coverage without changing the selected geometry. */
+    explain?: boolean;
 }
 declare class OPFCompositionError extends Error {
     readonly diagnostics: LayoutDiagnostic[];
     readonly code = "layout-overflow";
-    constructor(diagnostics: LayoutDiagnostic[]);
+    readonly explanation?: CompositionExplanation;
+    constructor(diagnostics: LayoutDiagnostic[], explanation?: CompositionExplanation);
 }
 /** Deterministic estimate, not a font shaping engine. Preserves explicit line breaks. */
 declare function measureText(text: string, fontSize: number): number;
 declare function wrapText(text: string, width: number, fontSize: number, measure?: MeasureTextWidth): string[];
 declare function fitText(text: string, box: LayoutBox, requestedSize?: number, minFontSize?: number, measure?: MeasureTextWidth): TextFit;
+interface QuoteContent {
+    text: string;
+    attribution?: string;
+    source?: string;
+}
+/** Source and displayed-text ranges are half-open UTF-16 offsets. Added punctuation has no source range. */
+interface QuoteTextSource {
+    path: string;
+    start: number;
+    end: number;
+    outputStart: number;
+    outputEnd: number;
+}
+interface QuoteTextPart {
+    role: 'body' | 'footer';
+    path: string;
+    text: string;
+    sources: QuoteTextSource[];
+    /** Available space, before fitting. Invalid dimensions remain visible in failed results. */
+    box: LayoutBox;
+    requestedFontSize: number;
+    minFontSize: number;
+    requestedStyle: TextStyle;
+    style: TextStyle;
+    /** Absent when the available box is invalid; never fit against an invented one-pixel box. */
+    fit?: TextFit;
+}
+interface QuoteLayoutDiagnostic extends LayoutDiagnostic {
+    reason: 'invalid-part-box' | 'part-outside-cell' | 'text-fit' | 'part-overlap';
+    parts: QuoteTextPart['role'][];
+}
+interface QuoteLayout {
+    algorithm: 'quote-flow-v1';
+    textMeasurement: 'estimated' | 'provided';
+    parts: QuoteTextPart[];
+    diagnostics: QuoteLayoutDiagnostic[];
+    overflow: boolean;
+}
+interface QuoteLayoutOptions {
+    /** Canvas short edge divided by 720. Insets retain the current 18 reference-pixel contract. */
+    scale?: number;
+    fonts?: Partial<FontFamilies>;
+    /** Readability floor in reference pixels, before canvas scaling. */
+    minFontSize?: number;
+    overflow?: Composition['overflow'];
+    path?: string;
+    textMeasurement?: TextMeasurement;
+}
+/**
+ * Allocate and measure quote body/footer space for composition, rendering and export. Callers must
+ * check overflow before accepting the parts. Line boxes are not shaped glyph or native raster bounds.
+ */
+declare function layoutQuote(value: string | QuoteContent, box: LayoutBox, options?: QuoteLayoutOptions): QuoteLayout;
+interface CodeContent {
+    source: string;
+    language?: string;
+    filename?: string;
+}
+interface CodeLineSegment {
+    kind: 'text' | 'tab';
+    start: number;
+    end: number;
+    /** Measured position relative to this displayed line's origin, in reference pixels. */
+    x: number;
+    width: number;
+}
+/** Exact half-open UTF-16 offsets into the part text, including consumed hard line breaks. */
+interface CodeLineSource {
+    start: number;
+    end: number;
+    nextStart: number;
+    boundary: 'soft' | 'hard' | 'end';
+    width: number;
+    /** Explicit tab placement is required in SVG; CSS tab-size alone does not implement it. */
+    segments: CodeLineSegment[];
+}
+interface CodeTextFit extends TextFit {
+    sourceLines: CodeLineSource[];
+    /** Tabs advance to the next multiple of four measured spaces from each displayed line's origin. */
+    tabSize: 4;
+    tabWidth: number;
+}
+interface CodeTextPart {
+    role: 'filename' | 'language' | 'body';
+    path: string;
+    /** Original text, without case conversion, whitespace normalization or discarded newlines. */
+    text: string;
+    sources: {
+        path: string;
+        start: number;
+        end: number;
+    }[];
+    generated: boolean;
+    box: LayoutBox;
+    requestedFontSize: number;
+    minFontSize: number;
+    requestedStyle: TextStyle;
+    style: TextStyle;
+    fit?: CodeTextFit;
+}
+interface CodeLayoutDiagnostic extends LayoutDiagnostic {
+    reason: 'invalid-part-box' | 'part-outside-cell' | 'text-fit' | 'part-overlap';
+    parts: CodeTextPart['role'][];
+}
+interface CodeLayout {
+    algorithm: 'code-flow-v1';
+    textMeasurement: 'estimated' | 'provided';
+    parts: CodeTextPart[];
+    diagnostics: CodeLayoutDiagnostic[];
+    overflow: boolean;
+}
+interface CodeLayoutOptions extends QuoteLayoutOptions {
+}
+/** Shared filename/language/body allocation. Consumers must reuse the accepted fits and styles. */
+declare function layoutCode(value: string | CodeContent, box: LayoutBox, options?: CodeLayoutOptions): CodeLayout;
 interface RichTextRun {
     text: string;
     bold?: boolean;
@@ -272,4 +426,4 @@ declare function resolveCanvasDimensions(input: unknown): {
     height: number;
 };
 
-export { type ComposeSlideOptions, type ComposedFlow, type ComposedGroup, type ComposedItem, type Composition, type CompositionTrack, type FontFamilies, type LayoutBox, type LayoutDiagnostic, type ListEntryLayout, type ListFit, type ListText, type ListValue, MAX_COMPOSITION_DEPTH, type MeasureTextWidth, OPFCompositionError, type RichTextFit, type RichTextFragment, type RichTextLine, type RichTextOptions, type RichTextRun, type SlideComposition, type TableBorder, type TableCellLayout, type TableCellStyle, type TableGrid, type TableGridCell, type TableGridIssue, type TableLayout, type TableLayoutOptions, type TableRowLayout, type TextFit, type TextMeasurement, type TextStyle, composeSlide, fitList, fitRichText, fitText, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText };
+export { type CodeContent, type CodeLayout, type CodeLayoutDiagnostic, type CodeLayoutOptions, type CodeLineSegment, type CodeLineSource, type CodeTextFit, type CodeTextPart, type ComposeSlideOptions, type ComposedFlow, type ComposedGroup, type ComposedItem, type Composition, type CompositionCandidate, type CompositionDecision, type CompositionExplanation, type CompositionPenalties, type CompositionTrack, type FontFamilies, type LayoutBox, type LayoutDiagnostic, type ListEntryLayout, type ListFit, type ListText, type ListValue, MAX_COMPOSITION_DEPTH, type MeasureTextWidth, OPFCompositionError, type QuoteContent, type QuoteLayout, type QuoteLayoutDiagnostic, type QuoteLayoutOptions, type QuoteTextPart, type QuoteTextSource, type RichTextFit, type RichTextFragment, type RichTextLine, type RichTextOptions, type RichTextRun, type SlideComposition, type TableBorder, type TableCellLayout, type TableCellStyle, type TableGrid, type TableGridCell, type TableGridIssue, type TableLayout, type TableLayoutOptions, type TableRowLayout, type TextFit, type TextMeasurement, type TextStyle, composeSlide, fitList, fitRichText, fitText, layoutCode, layoutQuote, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText };

package/dist/composition.js

@@ -1 +1 @@
-export { MAX_COMPOSITION_DEPTH, OPFCompositionError, composeSlide, fitList, fitRichText, fitText, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText } from './chunk-OVPWNQIJ.js';
+export { MAX_COMPOSITION_DEPTH, OPFCompositionError, composeSlide, fitList, fitRichText, fitText, layoutCode, layoutQuote, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText } from './chunk-JA5W5TVA.js';