@bendyline/squisq 2.13.12 → 2.13.14

package/dist/transform/index.d.ts

@@ -1,5 +1,6 @@
 import { T as Doc, t as ColorScheme, k as Block, by as TemplateBlock } from '../Doc-BhvotZx_.js';
-import { i as PageTransformHints } from '../materializePageSection-bLfqIy6j.js';
+import { l as PageTransformHints, n as PresentationBeatLayout, o as PresentationLayout, p as PresentationPlan } from '../materializePageSection-CWxou4mX.js';
+export { A as AUTHORED_PRESENTATION_LAYOUT, P as PRESENTATION_KEY, b as PRESENTATION_LAYOUTS, c as PRESENTATION_LIMITS, m as PresentationBeat, s as parsePresentationPlan, t as presentationLayoutFits, u as presentationStat, w as serializePresentationPlan } from '../materializePageSection-CWxou4mX.js';
 import { d as ExtractionType, E as ExtractedElement, b as ExtractionOptions } from '../contentExtractor-BNfVJV2U.js';
 import { f as BuildSpec, M as MarkdownBlockNode } from '../types-Zk8qYuaT.js';
 
@@ -321,66 +322,6 @@ declare function extractDocImages(blocks: Block[]): TransformImage[];
  */
 declare function analyzeBlocks(blocks: Block[], options?: ExtractionOptions): AnalyzedBlock[];
 
-/** A prominent number found inside a short stat-like string. */
-interface NumberHighlightMatch {
-    value: string;
-    index: number;
-    end: number;
-}
-
-/** A bounded presentation is a visual overlay on the canonical spoken script.
- * It lives in frontmatter so undo, copy, DBK, and ordinary Markdown saves carry
- * it atomically. Layout choices never replace the source prose or store seconds.
- */
-
-declare const PRESENTATION_KEY = "squisq-presentation";
-/** The layouts a summary (a headline and up to four points) can fill. */
-declare const PRESENTATION_LAYOUTS: readonly ["title", "divider", "statement", "emphasis", "quote", "stat", "definition", "list", "comparison", "steps", "image", "cards", "process", "cycle", "layers"];
-type PresentationLayout = (typeof PRESENTATION_LAYOUTS)[number];
-/** Shows a section's own block, with the template its author chose, instead of
- * a summary. A section shown this way is one slide for its whole narration. */
-declare const AUTHORED_PRESENTATION_LAYOUT = "authored";
-type PresentationBeatLayout = PresentationLayout | typeof AUTHORED_PRESENTATION_LAYOUT;
-/** The prominent number a key-number slide shows, and the line that states it. */
-declare function presentationStat(headline: string, points: readonly string[]): {
-    match: NumberHighlightMatch;
-    line: string;
-    index: number;
-} | null;
-/** Whether a summary can fill a layout: enough points for a list, steps,
- * cards, a process, a cycle (three) or a comparison; a prominent number for a key number; a short headline for a big
- * statement; and, for a quote, a headline found word for word in
- * `passage`, the source text the slide summarizes. An image slide also needs a
- * picture, which callers check. */
-declare function presentationLayoutFits(layout: PresentationLayout, headline: string, points: readonly string[], passage: string): boolean;
-interface PresentationBeat {
-    id: string;
-    sourceStart: number;
-    sourceEnd: number;
-    layout: PresentationBeatLayout;
-    headline: string;
-    points: string[];
-    imageSrc?: string;
-    /** The section's videos and diagrams shown beside this slide's text (`presentationMedia`). */
-    media?: string[];
-    /** Left out of the deck; the slide shown before it stays on screen instead. */
-    hidden?: true;
-}
-interface PresentationPlan {
-    version: 1;
-    sourceText: string;
-    origin: 'automatic' | 'ai';
-    beats: PresentationBeat[];
-}
-declare const PRESENTATION_LIMITS: {
-    readonly sourceCharacters: 40000;
-    readonly beats: 80;
-    readonly serializedCharacters: 160000;
-    readonly mediaPerBeat: 4;
-};
-declare function parsePresentationPlan(input: unknown): PresentationPlan | null;
-declare function serializePresentationPlan(plan: PresentationPlan): string;
-
 declare const PRESENTATION_HINTS_KEY = "squisq-presentation-hints";
 declare const DYNAMIC_PRESENTATION_STYLE = "dynamic-slides";
 /** A short, stable name for one slide's exact source passage. Saving it rather
@@ -466,4 +407,155 @@ interface PresentationMediaItem {
  * nearest narrated section at or before it. */
 declare function collectPresentationMedia(doc: Doc, sectionIds: string[]): Map<string, PresentationMediaItem[]>;
 
-export { AUTHORED_PRESENTATION_LAYOUT, type AnalyzedBlock, type BlockImage, DEFAULT_TRANSFORM_STYLE_ID, DYNAMIC_PRESENTATION_STYLE, type NarratedSegmentInput, type NarratedSegmentResult, type NarratedSegmentTransformOptions, type NarratedSegmentVideo, PRESENTATION_HINTS_KEY, PRESENTATION_KEY, PRESENTATION_LAYOUTS, PRESENTATION_LIMITS, type PresentationBeat, type PresentationBeatLayout, type PresentationBlockHint, type PresentationHints, type PresentationLayout, type PresentationMediaItem, type PresentationPlan, type TransformImage, type TransformOptions, type TransformResult, type TransformStyleConfig, type TransformStyleId, type TransformStyleInput, type TransformStyleRegistry, type TransformStyleSummary, allocateTiming, analyzeBlocks, applySavedPresentation, applyTransform, collectPresentationMedia, compilePresentationPlan, createPresentationPlan, createTransformStyleRegistry, defaultPresentationHints, extractDocImages, getTransformStyleIds, getTransformStyleSummaries, parsePresentationHints, parsePresentationPlan, presentationLayoutFits, presentationPassageKey, presentationSections, presentationStat, resolveTransformStyle, serializePresentationHints, serializePresentationPlan, transformNarratedSegment, usesDynamicPresentation };
+/**
+ * Grounding checks: does what an author put on a slide come from the source
+ * it illustrates?
+ *
+ * An AI author (a deck refiner, a video director) rewords and arranges; it must
+ * never add a fact. These pure checks are the gate its output passes before a
+ * slide ships, shared so every product holds generated slides to the same
+ * standard:
+ *
+ * - {@link ungroundedNumber}: every number shown is one the source states,
+ *   in digits or words (commas ignored, so "1400" matches "1,400" and "10"
+ *   matches "ten").
+ * - {@link isVerbatimQuote}: a quotation is the source's own words.
+ * - {@link isGroundedParaphrase}: a short label or point may trim and reorder,
+ *   but its numbers and most of its distinctive words come from the source.
+ * - {@link restatesHeadline}: a point that only repeats its headline.
+ * - {@link rangeEndOnly}: a number the source gives only as one end of a range
+ *   ("3 to 7 miles deep"). Shown as a single value — a count-up, one bar — it
+ *   misstates the source, though the number itself appears there.
+ *
+ * Checks report; callers decide what to drop. None of them can tell whether
+ * a slide is good, only whether it is faithful.
+ *
+ * Related: `doc/templates/authoringGuide.ts` (what authors are told),
+ * `transform/conceptReveal.ts` (matching points to the sentences that say them).
+ */
+/**
+ * Lowercased text with typographic quotes and dashes folded and other
+ * punctuation spaced out; apostrophes, percent signs and hyphens survive.
+ */
+declare function normalizeGroundingText(text: string): string;
+/** The numbers a value shows, commas dropped: "1,500 to 2,500 feet" → ["1500", "2500"]. */
+declare function numbersIn(value: string | number): string[];
+/**
+ * Numbers a source spells out, two to ninety-nine ("ten peaks", "twenty-five
+ * years"), with where each starts. "One" is left out: it is more often a
+ * pronoun than a count.
+ */
+declare function spelledNumbers(source: string): Array<{
+    value: string;
+    index: number;
+}>;
+/** Every number a source states, in digits or spelled out, for repeated lookups. */
+declare function sourceNumbers(source: string): Set<string>;
+/**
+ * The first number among `values` that the source does not state, or
+ * `undefined` when every one is grounded.
+ */
+declare function ungroundedNumber(values: string | number | ReadonlyArray<string | number>, source: string | ReadonlySet<string>): string | undefined;
+/** Sentences of a text, split after ., ! or ? and at line breaks. */
+declare function groundingSentences(text: string): string[];
+interface VerbatimQuoteOptions {
+    /** The source's sentences, when the caller splits them its own way. */
+    sentences?: readonly string[];
+    /** Share of the quote's words one sentence must hold (default 0.9). */
+    minShare?: number;
+}
+/**
+ * Whether `quote` is the source's own words: a span of the source once both
+ * are normalized, or a sentence of it holding nearly all of the quote's words
+ * (a dropped comma or a trimmed clause still passes; a paraphrase does not).
+ */
+declare function isVerbatimQuote(quote: string, source: string, options?: VerbatimQuoteOptions): boolean;
+/**
+ * Distinctive words of a text — four letters or longer and not a common
+ * word — by their first four letters, so "writing" matches "write" and a
+ * possessive matches its noun.
+ */
+declare function distinctiveStems(text: string): string[];
+interface ParaphraseOptions {
+    /** Share of the text's distinctive words the source must use (default ⅔). */
+    minShare?: number;
+}
+/**
+ * Whether a short paraphrase (a label, a point, a list item) is grounded:
+ * every number it shows is stated in the source, and at least `minShare` of
+ * its distinctive words come from the source. A text with no distinctive
+ * words ("Then", "By 1900") passes on its numbers alone.
+ */
+declare function isGroundedParaphrase(text: string, source: string, options?: ParaphraseOptions): boolean;
+/**
+ * Whether a point mostly repeats its headline (most of its words are the
+ * headline's) or merely continues it (it holds every word of a headline of
+ * three or more), so it adds nothing to the slide.
+ */
+declare function restatesHeadline(point: string, headline: string): boolean;
+/** A range a source states, such as "3 to 7", "1,500–2,500" or "between 10 and 12". */
+interface StatedRange {
+    /** The lower end as written, commas dropped. */
+    low: string;
+    /** The upper end as written, commas dropped. */
+    high: string;
+    /** The range as it appears in the source. */
+    text: string;
+    /** Where it starts in the source. */
+    index: number;
+}
+/** Every range the source states, in order. */
+declare function statedRanges(source: string): StatedRange[];
+/**
+ * When every place the source states `value` is one end of a range, the
+ * first such range; otherwise `undefined`. Use it on numbers a slide shows
+ * as one value — a count-up, a single bar, a comparison — where "3 to 7 miles
+ * deep" drawn as 7 says something the source does not. Dates are ranges of
+ * a different kind ("1939–1945" names two years); don't check them here.
+ */
+declare function rangeEndOnly(value: string | number, source: string): StatedRange | undefined;
+
+/**
+ * Concept reveals: a concept slide (`cards`, `process`, `cycle`, `layers`)
+ * that shows its ideas one at a time, each as the narration reaches it.
+ *
+ * Two steps, so any host with narration can use them: find where in the
+ * script each idea is spoken ({@link matchPointsToSentences}), then turn
+ * those moments into the slide's build ({@link conceptRevealTiming}). The
+ * presentation compiler does both from a plan; a host with its own script
+ * format (a video director's beats) can time ideas by phrase instead and use
+ * only the second step.
+ *
+ * The build's `sourceText` guard is named from the same step texts the
+ * template draws (`conceptBuildStepTexts`), so the renderer accepts the
+ * timing without drawing the block first; ideas the narration cannot place
+ * reveal evenly over the slide instead.
+ *
+ * Related: `doc/templates/conceptBlocks.ts`, `doc/builds.ts`
+ * (`resolveBuildTimeline`), `transform/presentationCompiler.ts`.
+ */
+
+declare const CONCEPT_TEMPLATES: readonly ["cards", "process", "cycle", "layers"];
+type ConceptTemplate = (typeof CONCEPT_TEMPLATES)[number];
+/** The concept template a name denotes, or `undefined`. */
+declare function conceptTemplate(template: string): ConceptTemplate | undefined;
+/**
+ * Where in `sourceText[start, end)` each point is spoken: the offset of the
+ * sentence it shares the most words with (at least two). Points must land
+ * in order (two may share a sentence); `undefined` when one cannot be placed
+ * or would land before the point ahead of it.
+ */
+declare function matchPointsToSentences(points: readonly string[], sourceText: string, start: number, end: number): number[] | undefined;
+/** How a concept slide reveals its ideas unless its author says otherwise. */
+declare function conceptBuildSpec(): BuildSpec;
+/**
+ * A concept slide's build: its ideas appear at `itemTimes` (seconds on the
+ * same clock as `start` and `end`, the slide's span). Each reveal waits for a
+ * short lead into the slide and lands before its end; the first idea lands
+ * as the headline settles even when its words come later, so the slide never
+ * sits on its headline alone. Without one time per idea, the build reveals
+ * the ideas evenly.
+ */
+declare function conceptRevealTiming(template: ConceptTemplate, items: readonly string[], itemTimes: readonly number[] | undefined, start: number, end: number): Pick<Block, 'build' | 'buildTiming'>;
+
+export { type AnalyzedBlock, type BlockImage, CONCEPT_TEMPLATES, type ConceptTemplate, DEFAULT_TRANSFORM_STYLE_ID, DYNAMIC_PRESENTATION_STYLE, type NarratedSegmentInput, type NarratedSegmentResult, type NarratedSegmentTransformOptions, type NarratedSegmentVideo, PRESENTATION_HINTS_KEY, type ParaphraseOptions, PresentationBeatLayout, type PresentationBlockHint, type PresentationHints, PresentationLayout, type PresentationMediaItem, PresentationPlan, type StatedRange, type TransformImage, type TransformOptions, type TransformResult, type TransformStyleConfig, type TransformStyleId, type TransformStyleInput, type TransformStyleRegistry, type TransformStyleSummary, type VerbatimQuoteOptions, allocateTiming, analyzeBlocks, applySavedPresentation, applyTransform, collectPresentationMedia, compilePresentationPlan, conceptBuildSpec, conceptRevealTiming, conceptTemplate, createPresentationPlan, createTransformStyleRegistry, defaultPresentationHints, distinctiveStems, extractDocImages, getTransformStyleIds, getTransformStyleSummaries, groundingSentences, isGroundedParaphrase, isVerbatimQuote, matchPointsToSentences, normalizeGroundingText, numbersIn, parsePresentationHints, presentationPassageKey, presentationSections, rangeEndOnly, resolveTransformStyle, restatesHeadline, serializePresentationHints, sourceNumbers, spelledNumbers, statedRanges, transformNarratedSegment, ungroundedNumber, usesDynamicPresentation };

package/dist/transform/index.js

@@ -1,5 +1,20 @@
+import {
+  distinctiveStems,
+  groundingSentences,
+  isGroundedParaphrase,
+  isVerbatimQuote,
+  normalizeGroundingText,
+  numbersIn,
+  rangeEndOnly,
+  restatesHeadline,
+  sourceNumbers,
+  spelledNumbers,
+  statedRanges,
+  ungroundedNumber
+} from "../chunk-FCB6JLWB.js";
 import {
   AUTHORED_PRESENTATION_LAYOUT,
+  CONCEPT_TEMPLATES,
   DEFAULT_TRANSFORM_STYLE_ID,
   DYNAMIC_PRESENTATION_STYLE,
   PRESENTATION_HINTS_KEY,
@@ -12,12 +27,16 @@ import {
   applyTransform,
   collectPresentationMedia,
   compilePresentationPlan,
+  conceptBuildSpec,
+  conceptRevealTiming,
+  conceptTemplate,
   createPresentationPlan,
   createTransformStyleRegistry,
   defaultPresentationHints,
   extractDocImages,
   getTransformStyleIds,
   getTransformStyleSummaries,
+  matchPointsToSentences,
   parsePresentationHints,
   parsePresentationPlan,
   presentationLayoutFits,
@@ -29,8 +48,8 @@ import {
   serializePresentationPlan,
   transformNarratedSegment,
   usesDynamicPresentation
-} from "../chunk-OUSEEUEC.js";
-import "../chunk-QJQQO3K4.js";
+} from "../chunk-YQQWE4HG.js";
+import "../chunk-CTT4XAGO.js";
 import "../chunk-SGNWO7OF.js";
 import "../chunk-SVN7T6BK.js";
 import "../chunk-FUBMT6SJ.js";
@@ -41,10 +60,12 @@ import "../chunk-7MS26OXD.js";
 import "../chunk-L3KSFLTP.js";
 import "../chunk-CZ7AUSLI.js";
 import "../chunk-P53Z4RYC.js";
+import "../chunk-L4AFSOT3.js";
 import "../chunk-GHOPHGOK.js";
 import "../chunk-XRW6P7IF.js";
 export {
   AUTHORED_PRESENTATION_LAYOUT,
+  CONCEPT_TEMPLATES,
   DEFAULT_TRANSFORM_STYLE_ID,
   DYNAMIC_PRESENTATION_STYLE,
   PRESENTATION_HINTS_KEY,
@@ -57,21 +78,37 @@ export {
   applyTransform,
   collectPresentationMedia,
   compilePresentationPlan,
+  conceptBuildSpec,
+  conceptRevealTiming,
+  conceptTemplate,
   createPresentationPlan,
   createTransformStyleRegistry,
   defaultPresentationHints,
+  distinctiveStems,
   extractDocImages,
   getTransformStyleIds,
   getTransformStyleSummaries,
+  groundingSentences,
+  isGroundedParaphrase,
+  isVerbatimQuote,
+  matchPointsToSentences,
+  normalizeGroundingText,
+  numbersIn,
   parsePresentationHints,
   parsePresentationPlan,
   presentationLayoutFits,
   presentationPassageKey,
   presentationSections,
   presentationStat,
+  rangeEndOnly,
   resolveTransformStyle,
+  restatesHeadline,
   serializePresentationHints,
   serializePresentationPlan,
+  sourceNumbers,
+  spelledNumbers,
+  statedRanges,
   transformNarratedSegment,
+  ungroundedNumber,
   usesDynamicPresentation
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq",
-  "version": "2.13.12",
+  "version": "2.13.14",
   "description": "Headless utilities for doc/block rendering, spatial math, Markdown, and storage",
   "license": "MIT",
   "author": "Bendyline",