@sushichan044/kg-core 0.6.4 → 0.7.0

package/README.md

@@ -13,23 +13,38 @@ or DOM behavior.
 pnpm add @sushichan044/kg-core
 ```
 
+## Entry points
+
+The package is split by what you are doing, so an application only ever sees the
+surface it needs.
+
+| Entry                          | For                                                                                             |
+| ------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `@sushichan044/kg-core`        | Running the pipeline and reading what comes out: parse, compose, settings, results, diagnostics |
+| `@sushichan044/kg-core/lint`   | Proofreading — running the rules, and writing your own                                          |
+| `@sushichan044/kg-core/plugin` | Supplying an implementation to core: a parser, a composer, or a measurer                        |
+
+A name is exported only when one of those three needs to write it. Helpers core
+keeps for itself are not part of the API.
+
 ## Processing pipeline
 
 ```ts
 import {
   ComposeError,
   composeManuscript,
-  createNovelComposer,
-  createDefaultProofreadingRules,
   NovelCompositionSettings,
   novelComposer,
   ParseError,
   parseManuscript,
   kakuyomuParser,
   pixivParser,
+} from "@sushichan044/kg-core";
+import {
+  createDefaultProofreadingRules,
   ProofreadError,
   proofreadManuscript,
-} from "@sushichan044/kg-core";
+} from "@sushichan044/kg-core/lint";
 
 const parsed = parseManuscript(source, { parser: kakuyomuParser });
 if (!parsed.ok) throw new Error(ParseError.describe(parsed.error));
@@ -63,14 +78,29 @@ whether it ended naturally, by shrinking, stretching, hanging, forcing, or reach
 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.
+and selects line breaks over the whole source paragraph. The space between two
+classes follows appendix 表1 of JLReq: a half em before an opening bracket and after
+a closing bracket, comma, or full stop, a quarter em on either side of a middle dot,
+a quarter em between Japanese and a numeral, unit symbol, or Western character, and
+solid where two of those punctuation marks meet.
+
+An overflowing line is answered by reducing that space or by hanging a comma or full
+stop; a short line is answered by stretching eligible space; a line that admits none
+of these is forced. The choice is made for the paragraph rather than line by line,
+minimizing in order the number of forced lines, then stretched, then hanging, then
+shrunk lines that spent visible space. Which space may be reduced, and in which
+order, follows JLReq 3.8.3 and appendix 表3: the space at the line end goes first and
+costs the paragraph nothing, because it is invisible once that character lands there;
+then a middle dot's quarters, then the half em before an opening bracket or after a
+closing bracket or comma, then the Japanese-to-Western quarter down to an eighth. The
+half em after a mid-line full stop marks the end of a sentence and is never reduced,
+and neither is the half em that keeps a line-head opening bracket off the edge.
+
+The composer also 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),
+[JLReq](https://www.w3.org/TR/jlreq/#mixed_text_composition_in_vertical_writing_mode),
 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
@@ -82,6 +112,8 @@ advance by half an em. Supply a synchronous measurer when the caller has more ac
 font metrics. Base-text requests also include the selected `presentation`:
 
 ```ts
+import { createNovelComposer } from "@sushichan044/kg-core/plugin";
+
 const composer = createNovelComposer({
   measurer: (request) => ({
     advanceEm: measureWithAvailableFont(request.text, {
@@ -104,6 +136,10 @@ parser result with mismatched `mono` or `jukugo` segment counts is invalid.
 
 ## Extensions and validation
 
+Everything in this section comes from `@sushichan044/kg-core/plugin`, except
+proofreading rules, which are authored against `@sushichan044/kg-core/lint`
+alongside the built-in ones.
+
 Parsers implement `ManuscriptParser`. Composers implement `ManuscriptComposer`
 and provide Valibot schemas for their settings and layout. Proofreading rules
 carry `kind: "parsed"` or `kind: "composed"` to declare which manuscript they
@@ -120,6 +156,14 @@ same name, holding its schema and operations: `ManuscriptRange.merge`,
 inferred from the schemas with `v.InferOutput`; source, display, and grapheme
 ranges are distinct branded types, and plugin IDs are branded `NamespacedId`.
 
+A companion object is exported as a value only when one of the three roles
+calls something on it. Concepts you only ever read out of a composed layout —
+`NovelPage`, `ComposedGlyph`, `LineBreakResult`, and the like — are exported as
+types alone, so their schemas are not part of the API. The settings you persist
+and re-validate keep theirs: `NovelCompositionSettings.schema`,
+`ManuscriptAppearanceSettings.schema`, `ManuscriptOffsets.schema`,
+`NovelFlowSettings.schema`, and the appearance picklists.
+
 Processing functions return `ManuscriptResult`: success carries warnings, and
 failure carries exactly one error from a discriminated union, so callers can
 `switch` on `error.kind` exhaustively. Each error variant exposes its context
@@ -135,6 +179,10 @@ or recalculate locations.
 
 ## Proofreading rules
 
+Proofreading has its own entry point, `@sushichan044/kg-core/lint`. Nothing in
+the root entry imports from it, so an application that only parses and composes
+never pulls the rules into its bundle.
+
 `createDefaultProofreadingRules()` returns the rules whose answer does not
 depend on the work: how a paragraph opens and how far it is indented,
 punctuation before a closing bracket, spacing after `！` and `？`, ellipsis and
@@ -152,7 +200,7 @@ import {
   consistentNumeralWidthRule,
   createConsistentKanjiOpeningRule,
   createDefaultProofreadingRules,
-} from "@sushichan044/kg-core";
+} from "@sushichan044/kg-core/lint";
 
 const rules = [
   ...createDefaultProofreadingRules(),