@sushichan044/kg-core 0.6.2 → 0.6.4

package/README.md

@@ -19,9 +19,10 @@ pnpm add @sushichan044/kg-core
 import {
   ComposeError,
   composeManuscript,
+  createNovelComposer,
   createDefaultProofreadingRules,
-  ManuscriptCompositionSettings,
-  manuscriptGridComposer,
+  NovelCompositionSettings,
+  novelComposer,
   ParseError,
   parseManuscript,
   kakuyomuParser,
@@ -34,8 +35,8 @@ const parsed = parseManuscript(source, { parser: kakuyomuParser });
 if (!parsed.ok) throw new Error(ParseError.describe(parsed.error));
 
 const composed = composeManuscript(parsed.value, {
-  composer: manuscriptGridComposer,
-  settings: ManuscriptCompositionSettings.defaults,
+  composer: novelComposer,
+  settings: NovelCompositionSettings.defaults,
 });
 if (!composed.ok) throw new Error(ComposeError.describe(composed.error));
 
@@ -52,11 +53,54 @@ const diagnostics = [...parsed.warnings, ...proofread.value];
 normalizes Kakuyomu ruby and emphasis marks. Malformed or unknown notation remains
 visible and produces a parser warning.
 
-`composeManuscript` requires a composer. The built-in grid composer produces a
-self-contained snapshot containing the parsed manuscript, accepted settings,
-geometry, statistics, and page/stage/line/cell hierarchy. Every occupied
-element has source, display, and grapheme ranges; empty placement elements use
-`null`.
+`composeManuscript` requires a composer. The built-in `novelComposer` produces
+a self-contained snapshot containing the parsed manuscript, accepted settings,
+geometry, statistics, and a page/stage/line hierarchy. Lines contain positioned
+inline items and annotation fragments. `glyph` items distinguish their typographic
+`layoutSpan` from their visual `renderSpan`; `glue`, `kern`, and `suppressed` items
+preserve every spacing decision. Each line also records its `inlineSizeEm` and
+whether it ended naturally, by shrinking, stretching, hanging, forcing, or reaching
+the paragraph end.
+
+The composer classifies the core prose classes from JLReq, resolves pair spacing,
+and selects line breaks over the whole source paragraph. It prefers natural setting,
+then shrinking punctuation space, hanging a comma or full stop, stretching eligible
+space, and finally a forced emergency line. It owns Japanese line-start and line-end
+restrictions, inseparable punctuation, question/exclamation gap suppression, and
+ruby placement.
+
+The composer classifies vertical text before measuring and breaking lines. Following
+[JLReq](https://www.w3.org/TR/jlreq/#handling_of_western_text_in_vertical_writing),
+upright Latin initials and abbreviations advance by one em per character, Western
+words remain unbroken and render sideways, and two ASCII digits form one
+tate-chu-yoko unit. The resulting `VerticalTextPresentation` is carried by every
+glyph item, so renderers do not need to infer orientation independently.
+
+The default logical measurer uses East Asian Width in a Japanese context. Upright
+ASCII advances by one em; proportional ASCII and the members of a tate-chu-yoko unit
+advance by half an em. Supply a synchronous measurer when the caller has more accurate
+font metrics. Base-text requests also include the selected `presentation`:
+
+```ts
+const composer = createNovelComposer({
+  measurer: (request) => ({
+    advanceEm: measureWithAvailableFont(request.text, {
+      role: request.role,
+      fontPreset: request.fontPreset,
+      writingMode: request.writingMode,
+      ...(request.role === "base" ? { presentation: request.presentation } : {}),
+    }),
+  }),
+});
+```
+
+A measurer returns `{ advanceEm }` in logical em units. Negative or non-finite
+results reject the composition instead of producing a partial layout.
+
+Ruby annotations retain one of three associations: `group` for one reading over
+the entire base, `mono` for one reading segment per base grapheme, and `jukugo`
+for a compound whose segments remain associated with each base grapheme. A
+parser result with mismatched `mono` or `jukugo` segment counts is invalid.
 
 ## Extensions and validation
 
@@ -72,7 +116,7 @@ construct core's error types.
 
 Each concept lives in its own module as a type plus a companion object of the
 same name, holding its schema and operations: `ManuscriptRange.merge`,
-`PaperSize.of`, `ManuscriptCompositionSettings.defaults`, and so on. Types are
+`PaperSize.of`, `NovelCompositionSettings.defaults`, and so on. Types are
 inferred from the schemas with `v.InferOutput`; source, display, and grapheme
 ranges are distinct branded types, and plugin IDs are branded `NamespacedId`.