gammonview 2.0.0__tar.gz → 2.0.2__tar.gz

{gammonview-2.0.0 → gammonview-2.0.2}/CHANGELOG.md

@@ -13,6 +13,71 @@ when the repository was opened; they are kept because they record why things
 are the way they are — particularly the breaking changes and the measurements
 behind several design decisions. Dates are the tag dates.
 
+## 2.0.2 — 2026-10-12
+
+**A set-up start is written once** *(fix)*
+
+2.0.1's fix for v1 set-up starts went too far. A game whose first ply sets up
+the board *with* dice keeps that ply as a ply, and the writers then also took
+the game's `initial_board` as a second start, so a rewritten file read back
+with an extra set-up ply in front and every later ply one place out. Both
+writers now take `initial_board` as the start only when the game has no
+leading set-up ply of either kind, which is the v1 case 2.0.1 was for.
+
+## 2.0.1 — 2026-10-10
+
+**Plies are counted the way v2 counts them** *(fix)*
+
+OGXM counts plies from the alternative, as gnubg does, so a 3-ply search is `checker_ply` 2 in
+the file; HedgeHog's author confirmed this as the convention. We wrote our own
+count, so other readers took our 3ply for 4-ply, and we read HedgeHog's 3-ply
+as 2ply. The writer now subtracts one from `checker_ply`, `cube_ply` and a
+rollout's `move_ply`, and the reader adds it back. Documents keep the count
+players use. A file of ours written by 2.0.0 still reads as it did: blocks
+written since carry `plies=gnubg` in their `x-gammonview-analysis` annotation,
+and a block of ours without it is read unshifted.
+
+**`site` is never derived** *(change)*
+
+The reader filled a missing `site` in from `city`, else the platform, and the
+writer left out a `site` that matched them. Choosing a place to show is the
+viewer's call, not the codec's, so `site` now reads back exactly as written,
+and none when none was: a document with a city and no site keeps no site. The
+writer stores any `site` in `x-gammonview-site`. A 2.0.0 file that left out a
+site equal to its city now reads with no site.
+
+**Our analysis is named in other readers** *(change)*
+
+An analysis block now carries `model_name` "GammonView bgsage" beside its
+`model_id`. HedgeHog's viewer names an analysis by `model_name` alone, so a
+match analysed here and opened there showed no engine. The identifier is
+unchanged, so nothing that keys on it moves.
+
+**A v1 set-up start survives a rewrite** *(fix)*
+
+A v1 file states a game that starts from a set-up board in its `GAME` header,
+so a v1 read gives that game an `initial_board` and no leading set-position
+ply. The v2 writers took the start only from such a ply, so rewriting the file
+dropped the board, replayed the game from the opening, and flagged its plays
+illegal. Both writers now take a bare `initial_board` as the game's start; a
+leading set-up ply, where there is one, still wins.
+
+**Long text values are split, not refused** *(fix)*
+
+An event or a `site` too long for one v2 string is carried in our annotation,
+which the profile says is split over `key~1`, `key~2`, … — but only the
+analysis and annotation records were split, so the writer raised instead. Every
+`x-gammonview-` record is split now, at character boundaries. A player name
+past v2's 4 096 bytes, the one text field with no annotation to fall back on,
+is still refused, and the profile now says so.
+
+**`isPlayLegal` on a roll with no legal play** *(fix, JavaScript only)*
+
+`legalPlays` returned no `best` for a dance, so `isPlayLegal` — and with it
+`write_gvab` — threw a `TypeError` on a dice ply that recorded checker steps on
+a roll that could not be played, where the Python writer flagged the play
+illegal. The two writers now agree on such a file.
+
 ## 2.0.0 — 2026-10-08
 
 **`.gvab` is OGXM v2** *(format change)*

{gammonview-2.0.0 → gammonview-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gammonview
-Version: 2.0.0
+Version: 2.0.2
 Summary: Backgammon match analysis — the pure-Python OGXM/GVA codec (`gvformat`) plus bgsage-powered match and position analysis (`gvanalysis`).
 Project-URL: Homepage, https://github.com/ngvlamis/gammonview-analysis
 Project-URL: Repository, https://github.com/ngvlamis/gammonview-analysis

{gammonview-2.0.0 → gammonview-2.0.2}/docs/OGXM_JSON_SPEC_GAMMONVIEW.md

@@ -66,8 +66,10 @@ unknown sections, presence-bit tails a later spec adds), it rides along in
 - **Output only** keys are produced by a reader (or a converter) for display and
   ignored by the writer, which derives them again: `ogid_before`, `ogid_after`,
   `notation`, `diff`, `played_equity`, `eval.equity`, `game_index`,
-  `is_crawford`, `first_to_move`, `initial_board`, `action` (on a
-  `cube_decision`) and `analysis_info.preset`.
+  `is_crawford`, `first_to_move`, `action` (on a `cube_decision`) and
+  `analysis_info.preset`. `initial_board` is output only *unless* the game has
+  no leading set-up ply, which is how a v1 read states a set-up start; the
+  writer then takes the board from it.
 
 ---
 
@@ -342,7 +344,7 @@ analysis to a document that already has one promotes it to this form
 | `initial_cube_value` | uint | The cube's value when the game opens (a power of two, within `cube_limit`). Default-omitted at 1 | `GAME.initial_cube_value` |
 | `initial_cube_owner` | uint | 0 White, 1 Black, 2 centred. Default-omitted at 2 | `GAME.initial_cube_owner` |
 | `auto_doubles` | uint | Automatic doubles this game opened with. The cube's real starting value is `initial_cube_value · 2^auto_doubles`. Default-omitted at 0 | `GAME.auto_doubles` |
-| `initial_board` | int[26] | **Output only.** The board of a game that starts from a set-up position, as a read also states it as the game's first ply | `GAME.initial_board` |
+| `initial_board` | int[26] | The board of a game that starts from a set-up position, as a v2 read also states it as the game's first ply. **Output only** when that ply is there; a v1 read gives this key alone, and the writer then takes the start from it | `GAME.initial_board` |
 | `annotations` | Annotation[] | Notes on the game | `ANNO`, game scope |
 | `plies` | [Ply](#ply)[] | The game's actions in order | |
 
@@ -623,7 +625,7 @@ A hold with the cube dead has none.
 | `action` | string | **Output only.** `"no_double"` when holding is correct; else `"double_take"` (when `double_pass_equity ≥ double_take_equity`) or `"double_pass"` |
 | `equity_loss` | float | Fresh converter output only (0.0 for a correct hold); not stored, absent in a read. The error belongs to `missed_double` |
 | `eval` | Eval | The pre-roll probabilities |
-| `decision` | bool | Whether this cube decision counted as a PR decision (not trivial). **Absent when a `missed_double` sits beside it** in a block of ours or in a v1 read — that record carries the count, so one cube is never counted twice. (A block of another producer completed by `basefill` currently gets one; see [`OGXM_COMPUTED_FIELDS.md`](OGXM_COMPUTED_FIELDS.md)) |
+| `decision` | bool | Whether this cube decision counted as a PR decision (not trivial). **Absent when a `missed_double` sits beside it** in a block of ours or in a v1 read — that record carries the count, so one cube is never counted twice. A block of another producer completed by `basefill` leaves it absent too; see [`OGXM_COMPUTED_FIELDS.md`](OGXM_COMPUTED_FIELDS.md) |
 | `eval_level` | string | The label of the cube result used. Our blocks only |
 | `level`, `take_point`, `window_searched`, `is_optional`, `is_free_cube`, `cubeful_take_value`, `currency`, `producer_ref`, `annotations` | | See [Per-decision v2 fields](#per-decision-v2-fields) |
 
@@ -921,8 +923,11 @@ The v1 byte layout is frozen in
 Those of v2 (spec §10): 1 000 games, 1 500 plies per game, 100 000 plies in a
 file, 1 024 alternatives per decision, 64 analysis blocks, 4 096 bytes per
 string, 4 096 annotations (256 KiB) and 256 drawings per annotation, a video URL
-of 512 bytes. The writer raises `ValueError` past a string or annotation limit and cuts an
-alternatives list at 1 024; the game and ply counts are not checked here.
+of 512 bytes. The writer cuts an alternatives list at 1 024, and carries a
+string past a field's own cap in an `x-gammonview-` annotation, split over as
+many records as it needs. It raises `ValueError` past the game, ply, block and
+annotation limits, and for a player name past 4 096 bytes, which has no
+annotation to fall back on.
 
 ---
 

{gammonview-2.0.0 → gammonview-2.0.2}/docs/OGXM_V2_PROFILE.md

@@ -37,7 +37,7 @@ below over the whole sample corpus and against the reference codec.
 | `stage`, `round`, `table`, `city`, `country`, `event_url`, `match_ref` | the same fields |
 | `platform` | v2's `site`: the platform's host name. Renamed because our `site` predates it |
 | `white_profile`, `black_profile` | the `player` records (4.1): `user_id`, `rating` (a float, to 0.01), `rating_system`, `country`, `kind` |
-| `site` | `x-gammonview-site`, unless it is what the reader would derive anyway: `city`, else `platform`. Ours is whatever the source called the place, sometimes a city and sometimes a platform, and nothing tells which |
+| `site` | `x-gammonview-site`, always. Ours is whatever the source or the user called the place, sometimes a city and sometimes a platform, and nothing tells which; it is never derived from `city` or `platform`, and a reader showing a place may fall back to them itself |
 | `games[].winner`, `points_won`, `is_lastgame` | `GAME` bits 0-2; `points_won` is written exactly when `winner` is |
 | `games[].termination`, `initial_cube_value`, `initial_cube_owner`, `auto_doubles` | the same `GAME` fields. The game's cube starts at `initial_cube_value · 2^auto_doubles`, owned by `initial_cube_owner` (5.3), in the OGIDs and in `gvanalysis` |
 | `games[].first_to_move`, `is_crawford`, `game_index` | derived, not stored |
@@ -71,6 +71,8 @@ has not assigned is kept whole, as `extras_raw`.
 A game that starts from a set-up board (a leading set-position ply with no
 dice) stores it as `GAME.initial_board` — unless the board is the opening
 position, which v2 never writes as an initial board, and then it stays a ply.
+A game read from a v1 file states its set-up board only as `initial_board`,
+with no such ply; the writer stores that as `GAME.initial_board` too.
 
 **Illegal plays.** A play that is not legal (M4) for its roll — or that any
 analysis block flags `illegal_move` — is written the way v2 records one: a
@@ -130,6 +132,16 @@ alternative overrides it only where its own differs, and a decision's or cube's
 `ply` is `checker_ply` / `cube_ply`. A luck record states its depth as
 `checker_ply`; the luck label travels once, in the block's annotation.
 
+**Counting plies.** v2 counts plies gnubg's way, from the alternative rather
+than from the position, and our documents count them the way players do: a
+search our document calls `3ply` is `checker_ply` 2 in the file, and a rollout
+whose moves are played at 2-ply has `move_ply` 1. The spec does not say this;
+HedgeHog's files count so and its author confirmed it as the convention. So the
+writer subtracts one from `checker_ply`, `cube_ply` and `move_ply`, and the
+reader adds it back. A block of ours written before gvformat 2.0.1 counted as
+its document does; it is told apart by its annotation, which since then carries
+`plies=gnubg`, and is read without the shift.
+
 **Checker decisions** carry the alternatives in their order, each with its
 steps, equity, probabilities when recorded, and `is_played`. v2 then derives
 the best equity (the first alternative's) and, when the played move is listed,
@@ -190,7 +202,7 @@ holds is split over `key`, `key~1`, `key~2`, ... and joined in that order.
 
 | Key | Scope | Value after `1:` |
 |---|---|---|
-| `x-gammonview-analysis/<analysis_id>` | match | `;`-separated items: `level=<label>` (the block's own level, when it is not the block preset; empty for none), `luck=<label>` (when the block has luck), `pr=<tokens>` (always present; it marks the block as ours), `frame=<entries>` (when plies carry a source frame) |
+| `x-gammonview-analysis/<analysis_id>` | match | `;`-separated items: `level=<label>` (the block's own level, when it is not the block preset; empty for none), `luck=<label>` (when the block has luck), `pr=<tokens>` (always present; it marks the block as ours), `plies=gnubg` (since gvformat 2.0.1: the block's levels count plies v2's way; see *Counting plies*), `frame=<entries>` (when plies carry a source frame) |
 | `x-gammonview-decisions/<analysis_id>` | ply | base64 of `DECS` records for this ply, in kind order. They stand in for `DECS`'s records of the same kind at that ply |
 | `x-gammonview-illegal-ply` | ply | the steps of the illegal play, `from/pips` joined by `,` (empty for a dance) |
 | `x-gammonview-site` | match | `site` |
@@ -234,7 +246,7 @@ decisions where the document says otherwise, each as its `ply_ref` and a letter:
 | met-id | a match block names its table: `kazaross-xg2` when the document named none |
 | mwc-frame | a source's frame (`mwc_frame`, §2) is carried by v2 only; v1 loses it |
 | default-omitted | a value equal to v2's default is not written, so it reads back absent: `variant` 0, a 0-0 `score_start`, `initial_cube_value` 1, `initial_cube_owner` 2 (centred), `auto_doubles` 0 or false, `rules_other` 0, a false flag, an empty string |
-| site-follows-place | a document with a `city` (else a `platform`) and no `site` reads back with that place as its `site` |
+| site-is-stated | `site` reads back exactly as written, and a document with none reads back with none, whatever its `city` or `platform` |
 | resign-derived | a `resign_value` equal to what the game's points and the cube give is not kept; only a different one is |
 | settle-millionths | a `settle_value` is held to a millionth of a point |
 | block-provenance | what v2's block record states (producer, completeness, coverage, model name, identifier and digest, engine build, currency, cube efficiency, tables, dials, completion time, sources, a level beyond the labels) is in the v2 read-back only; v1 has no field for it |
@@ -256,7 +268,8 @@ decisions where the document says otherwise, each as its `ply_ref` and a letter:
 The writer refuses, with a `ValueError`, what v2's limits cannot hold rather than
 writing an invalid file: more than 1000 games, more than 1500 plies in a game,
 more than 100000 plies, more than 64 analysis blocks (`write_gvab_v1`: more than
-16). `tests/test_ogxm2_limits.py` pins these and the cut above.
+16), and a player name longer than v2's 4096-byte string (the one text field
+with no annotation to fall back on). `tests/test_ogxm2_limits.py` pins these and the cut above.
 
 Each rule above is in `tests/test_ogxm2_writer.py`, which fails on any difference
 none of them explains.

{gammonview-2.0.0 → gammonview-2.0.2}/gvanalysis/match.py

@@ -95,6 +95,12 @@ from .progress import ProgressBar
 # engine upgrade invalidates the goldens anyway.
 MODEL_NAME = "gv-bgsage"
 
+#: What a reader shows for this analysis: v2's ``model_name``, beside the
+#: opaque ``model_id``. HedgeHog's viewer names an analysis by this field alone,
+#: so it is worded for a reader there, saying whose analysis it is; GammonView
+#: labels a ``gv-bgsage`` block from the identifier and never shows it.
+DISPLAY_NAME = "GammonView bgsage"
+
 
 def model_id() -> str:
     """``gv-bgsage/<bgsage version>`` -- the producer of this analysis.
@@ -631,6 +637,7 @@ def analyze_ogxm(
     return {
         "summary": {
             "engine": model_id(),
+            "model_name": DISPLAY_NAME,
             "engine_build": engine_build(),
             # Every decision of the match was looked at: v2's `complete`, as
             # against an incremental run that covered some of them.

{gammonview-2.0.0 → gammonview-2.0.2}/gvformat/binary.py

@@ -135,6 +135,8 @@ GVAN_CUBE_REC = 2
 GVAN_CHECKER_REC_V2 = 7
 GVAN_CUBE_REC_V2 = 6
 
+# v1's cap on a decision's alternatives, used by ``write_gvab_v1`` only. v2
+# holds 1024 (``MAX_ALTS`` in ogxm2_writer).
 MAX_ALTS_PER_DECISION = 50
 
 # The largest hop a ply record can hold. A move step is one byte -- the start

{gammonview-2.0.0 → gammonview-2.0.2}/gvformat/export.py

@@ -1552,6 +1552,7 @@ def to_ogxm_json(result: dict, *, keep_orientation: bool = False) -> dict:
             # bgsage its version, so the label arrives in the summary;
             # the bare fallback keeps an older caller's output valid.
             "model_id": summary.get("engine") or "bgsage",
+            **({"model_name": summary["model_name"]} if summary.get("model_name") else {}),
             "timestamp": ts,
             # What ran it, and that it ran the whole match (v2's `engine_build`
             # and `complete`); supplied for the same reason as `model_id`.

{gammonview-2.0.0 → gammonview-2.0.2}/gvformat/ogxm2.py

@@ -119,6 +119,11 @@ CURRENCY_CUBEFUL_MATCH = 2
 # holds; every value starts with GV_FORMAT.
 GV_FORMAT = "1:"
 GV_KEY_ANALYSIS = "x-gammonview-analysis/"
+#: The ``x-gammonview-analysis`` item saying the block counts plies v2's way
+#: (``PLY_SHIFT``). Written since gvformat 2.0.1; a block of ours without it
+#: counts them as its document does.
+GV_ITEM_PLIES = "plies"
+GV_PLIES_GNUBG = "gnubg"
 GV_KEY_DECISIONS = "x-gammonview-decisions/"
 GV_KEY_ILLEGAL_PLY = "x-gammonview-illegal-ply"
 GV_KEY_SITE = "x-gammonview-site"
@@ -354,6 +359,37 @@ def _level(cur: _Cursor) -> dict:
     return lv
 
 
+#: How v2 counts plies: gnubg's way, from the alternative rather than from the
+#: position, so a search a document calls ``3ply`` is ``checker_ply`` 2 on the
+#: wire. HedgeHog's own files count so, and its author confirmed it as the
+#: convention (the spec does not say). A document keeps the count players use;
+#: the codec moves by this much at the boundary, both ways.
+PLY_SHIFT = 1
+
+
+def shift_level(lv: dict | None, by: int) -> None:
+    """Move a level's depths -- ``checker_ply``, ``cube_ply`` and a rollout's
+    ``move_ply`` -- by ``by``, in place, never below 0."""
+    if not lv:
+        return
+    for k in ("checker_ply", "cube_ply"):
+        if k in lv:
+            lv[k] = max(lv[k] + by, 0)
+    r = lv.get("rollout")
+    if r and "move_ply" in r:
+        r["move_ply"] = max(r["move_ply"] + by, 0)
+
+
+def shift_levels(anal: dict, decisions, by: int) -> None:
+    """``shift_level`` over a block's level and every level its decision
+    records (``_decode_decs``'s) and their alternatives state."""
+    shift_level(anal.get("level"), by)
+    for d in decisions:
+        shift_level(d.get("level"), by)
+        for alt in d.get("alternatives") or []:
+            shift_level(alt.get("level"), by)
+
+
 def _resolve(parent: dict, override: dict | None) -> dict:
     """The effective level: each field from the innermost tier carrying it."""
     if not override:
@@ -1842,10 +1878,10 @@ def read_ogxm2(data: bytes, *, verify_crc: bool = True, derive_ogids: bool = Tru
             ogxm[name] = {**ogxm.get(name, {}), **restored}
     for gi, game in enumerate(games):
         _restore_fields(game, gv_game, gi, GV_GAME_FIELDS)
-    # `site` is where the match was played: our annotation, else v2's `city`,
-    # else the platform's host name.
-    ogxm["site"] = (gv_match[(0, GV_KEY_SITE)] if (0, GV_KEY_SITE) in gv_match
-                    else ogxm.get("city") or ogxm.get("platform") or None)
+    # `site` is ours, free text, and v2 has no field for it: it is what our
+    # annotation says, or nothing. It is never derived from `city` or the
+    # platform -- that is a display choice, and the codec makes none.
+    ogxm["site"] = gv_match.get((0, GV_KEY_SITE))
     if (0, GV_KEY_SCORE) in gv_match:
         try:
             ogxm["white_score"], ogxm["black_score"] = (
@@ -1897,14 +1933,24 @@ def read_ogxm2(data: bytes, *, verify_crc: bool = True, derive_ogids: bool = Tru
     decoded = []
     base_blocks = []
     ours_ids: set = set()
+    recounted: set = set()
     alt_maps: dict = {}
     for blk in blocks:
         aid = blk["anal"]["analysis_id"]
         ours = None
+        items = None
         if (0, GV_KEY_ANALYSIS + aid) in gv_match:
-            ours_ids.add(aid)
             items = dict(item.partition("=")[::2]
                          for item in gv_match[(0, GV_KEY_ANALYSIS + aid)].split(";") if item)
+        # Every producer counts plies v2's way except our writer before
+        # gvformat 2.0.1, whose blocks say so by not naming the count.
+        shift = items is None or items.get(GV_ITEM_PLIES) == GV_PLIES_GNUBG
+        if shift:
+            shift_levels(blk["anal"], blk["decisions"], PLY_SHIFT)
+        elif items is not None:
+            recounted.add(aid)
+        if items is not None:
+            ours_ids.add(aid)
             extra = {}
             for (ref, key), value in gv_ply.items():
                 if key == GV_KEY_DECISIONS + aid:
@@ -1913,6 +1959,8 @@ def read_ogxm2(data: bytes, *, verify_crc: bool = True, derive_ogids: bool = Tru
                     except ValueError as exc:
                         raise GvabError(f"annotation on ply {ref} is not base64") from exc
                     recs = _decode_decs(raw)
+                    if shift:
+                        shift_levels({}, recs, PLY_SHIFT)
                     if any(d["ply_ref"] != ref for d in recs):
                         raise GvabError(f"annotation on ply {ref} holds another ply's decision")
                     extra[ref] = recs
@@ -1958,5 +2006,5 @@ def read_ogxm2(data: bytes, *, verify_crc: bool = True, derive_ogids: bool = Tru
     # What the file holds that this document cannot: kept for the writer.
     from .ogxm2_passthrough import attach
     header = (struct.unpack_from("<H", data, 6)[0], struct.unpack_from("<H", data, 10)[0])
-    attach(ogxm, data, header, sections, annos, ours_ids)
+    attach(ogxm, data, header, sections, annos, ours_ids, recounted)
     return ogxm

{gammonview-2.0.0 → gammonview-2.0.2}/gvformat/ogxm2_passthrough.py

@@ -461,11 +461,14 @@ def v1_sign_to_v2(body: bytes) -> bytes | None:
 # ---------------------------------------------------------------------------
 
 def attach(ogxm: dict, data: bytes, header: tuple, sections: list, annos: list,
-           ours_ids: set) -> None:
+           ours_ids: set, recounted: set = frozenset()) -> None:
     """Attach ``_ogxm2_passthrough`` to ``ogxm`` when the file holds anything
     the document cannot. ``sections`` is ``[(type, offset, payload)]`` in file
-    order, ``annos`` the decoded ``ANNO`` records (each with its ``raw`` bytes)
-    and ``ours_ids`` the ``analysis_id`` of every block our writer made.
+    order, ``annos`` the decoded ``ANNO`` records (each with its ``raw`` bytes),
+    ``ours_ids`` the ``analysis_id`` of every block our writer made, and
+    ``recounted`` those of them that count plies as their document does (before
+    gvformat 2.0.1): their bytes are never kept, since the writer now counts
+    otherwise and would pair them with an annotation saying so.
 
     A file the writer reproduces byte for byte gets nothing, since there is
     nothing to keep: that is our own files, the common case, and it is decided
@@ -546,7 +549,7 @@ def attach(ogxm: dict, data: bytes, header: tuple, sections: list, annos: list,
         if mine is None or "decs" not in blk:
             return
         blk["fp"] = fingerprint(mine.anal, mine.decs, mine.anno_bytes())
-    pt["blocks"] = pt_blocks
+    pt["blocks"] = {aid: blk for aid, blk in pt_blocks.items() if aid not in recounted}
     # The clock and the video are in the document; the source's bytes stand for
     # them while the document still encodes to what they decoded to.
     for name, canon in (("clck", parts.clck), ("vido", parts.vido)):

{gammonview-2.0.0 → gammonview-2.0.2}/gvformat/ogxm2_writer.py

@@ -28,8 +28,8 @@ reader keeps and never interprets:
 ``x-gammonview-illegal-ply`` (ply scope)
     The steps of an illegal play that our document holds as a dice ply.
 ``x-gammonview-site``, ``x-gammonview-event`` (match scope)
-    A ``site`` that is neither the city nor the platform (v2's own ``site`` is a
-    host name), and an over-long ``event``.
+    Our free-text ``site``, which v2 has no field for (v2's own ``site`` is a
+    platform's host name), and an over-long ``event``.
 ``x-gammonview-<field>`` (match scope), ``x-gammonview-<side>_profile.<field>``, and
 ``x-gammonview-<field>`` at game scope
     A value v2 cannot hold (a string past its cap or outside its byte set, a
@@ -192,7 +192,10 @@ _ROLLOUT_UINTS = ("trials", "truncation_depth", "move_ply", "variance_reduction"
 
 
 def _level_bytes(lv: dict) -> bytes:
-    """A ``level`` record from an override (``_level_diff``'s shape)."""
+    """A ``level`` record from an override (``_level_diff``'s shape), its depths
+    counted v2's way (``R.PLY_SHIFT``)."""
+    lv = copy.deepcopy(lv)
+    R.shift_level(lv, -R.PLY_SHIFT)
     fields: dict[int, bytes] = {}
     if "preset" in lv:
         fields[0] = _str(lv["preset"])
@@ -456,6 +459,26 @@ def _game_start(g: dict, opening_abs: list) -> int:
                and [int(v) for v in first.get("set_position") or [0] * 26] != opening_abs)
 
 
+def _bare_initial_board(g: dict, opening_abs: list, start: int):
+    """The set-up board a game states only as ``initial_board``, or None.
+
+    A v1 read states a set-up start that way, with no leading ply (v1 kept the
+    board in the GAME header), so a v1 file rewritten as v2 would otherwise
+    lose its start -- and its plies, replayed from the opening, would be
+    flagged illegal. A leading set-up ply, where there is one, wins: a v2 read
+    states the board both ways. So does one *with* dice, which `_game_start`
+    keeps as a ply: the document already states its start, and taking
+    ``initial_board`` too would write that start twice."""
+    ib = g.get("initial_board")
+    if start or not isinstance(ib, list) or len(ib) != 26:
+        return None
+    plies = g.get("plies") or []
+    if plies and plies[0].get("action_id") == R.ACTION_SET_POSITION:
+        return None
+    board_abs = [int(v) for v in ib]
+    return None if board_abs == opening_abs else board_abs
+
+
 def ply_layout(doc: dict):
     """``(keys, starts)``: the ``(game, ply)`` of every ply v2 holds, in
     ``ply_ref`` order, and each game's leading set-up position (0 or 1) that it
@@ -543,8 +566,10 @@ class _Match:
             fields: dict[int, bytes] = {}
             start = _game_start(g, opening_abs)
             if start:
-                first = plies[0]
-                board_abs = [int(v) for v in first["set_position"]]
+                board_abs = [int(v) for v in plies[0]["set_position"]]
+            else:
+                board_abs = _bare_initial_board(g, opening_abs, start)
+            if board_abs is not None:
                 board = _absolute_to_p1(board_abs)
                 fields[3] = _board(board_abs)
 
@@ -832,11 +857,11 @@ class _Match:
             fields[11] = b""
         if doc.get("rated"):
             fields[25] = b""
-        # Our `site` is where the match was played, free text; v2 states the
-        # same in `city` (or names the platform). Only a `site` that is
-        # neither needs its own record.
+        # Our `site` is free text with no v2 field, so it always rides in its
+        # own record -- even when it repeats the city, since the reader no
+        # longer derives one from the other.
         site = doc.get("site")
-        if site and site != (doc.get("city") or doc.get("platform")):
+        if site:
             self.annos.append((SCOPE_MATCH, 0, R.GV_KEY_SITE, R.GV_FORMAT + site))
         variant = doc.get("variant") or 0
         if not _is_uint(variant):
@@ -1444,12 +1469,21 @@ def _flag_exceptions(doc_obj_by_key: dict, decoded_by_key: dict) -> list[str]:
 
 
 def _chunked(key: str, value: str) -> list[tuple[str, str]]:
-    """Split an ASCII value over ``key``, ``key~1``, ... to stay under
-    ``MAX_STRING``; the reader concatenates them in suffix order."""
+    """Split a value over ``key``, ``key~1``, ... to stay under ``MAX_STRING``
+    bytes; the reader concatenates them in suffix order. Cuts fall between
+    characters, never inside one's UTF-8 bytes."""
     room = MAX_STRING - 16
-    if len(value) <= room:
+    if len(value.encode("utf-8")) <= room:
         return [(key, value)]
-    parts = [value[i:i + room] for i in range(0, len(value), room)]
+    parts, cur, size = [], [], 0
+    for ch in value:
+        n = len(ch.encode("utf-8"))
+        if size + n > room:
+            parts.append("".join(cur))
+            cur, size = [], 0
+        cur.append(ch)
+        size += n
+    parts.append("".join(cur))
     return [(key if i == 0 else f"{key}~{i}", part) for i, part in enumerate(parts)]
 
 
@@ -1844,10 +1878,14 @@ def _encode(ogxm: dict) -> _Parts:
         # from the records just written, and keep only where the document
         # disagrees.
         anal_dec = R._decode_anal(anal)
+        decs_dec = R._decode_decs(decs_payload)
+        R.shift_levels(anal_dec, decs_dec, R.PLY_SHIFT)
         extra_dec = {ref: R._decode_decs(b"".join(rec for _k, rec in recs))
                      for ref, recs in extra.items()}
+        for recs in extra_dec.values():
+            R.shift_levels({}, recs, R.PLY_SHIFT)
         _info, decoded, _luck = R._v1_block(
-            anal_dec, R._decode_decs(decs_payload), match.ply_at, match.match_length,
+            anal_dec, decs_dec, match.ply_at, match.match_length,
             ours={"extra": extra_dec, "exceptions": set(), "illegal": match.illegal,
                   "frames": R._parse_frames(",".join(frames))})
         want = {(match.ref_of[key], key): select(p) for key, p in match.ply_at
@@ -1860,6 +1898,7 @@ def _encode(ogxm: dict) -> _Parts:
                 k == R.KIND_ROLL for recs in extra.values() for k, _b in recs):
             items.append("luck=" + quote(luck_label, safe=_SAFE))
         items.append("pr=" + ",".join(tokens))
+        items.append(f"{R.GV_ITEM_PLIES}={R.GV_PLIES_GNUBG}")
         if frames:
             items.append("frame=" + ",".join(frames))
         gv_annos: list[tuple[int, int, str, str]] = []
@@ -1929,9 +1968,12 @@ def _assemble(parts: _Parts, plan: P.Plan) -> bytes:
                                            ensure_ascii=False).encode("utf-8")).decode("ascii")
         ours += [(SCOPE_MATCH, 0, key, part)
                  for key, part in _chunked(R.GV_KEY_ANNOTATIONS, R.GV_FORMAT + text)]
-    for scope, ref, key, value in ours:
-        entries.append((P.anno_sort_key(scope, ref, None, None, None, key, None, len(entries)),
-                        _anno_record(scope, ref, key, value)))
+    # A value of ours past a string's length goes over ``key~1``, ``key~2``, ...
+    # (profile 3), whichever field it carries.
+    for scope, ref, key0, value0 in ours:
+        for key, value in _chunked(key0, value0):
+            entries.append((P.anno_sort_key(scope, ref, None, None, None, key, None, len(entries)),
+                            _anno_record(scope, ref, key, value)))
     if entries:
         entries.sort(key=lambda e: e[0])
         payload = b"".join(rec for _k, rec in entries)

{gammonview-2.0.0 → gammonview-2.0.2}/gvformat-js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gammonview/gvformat",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "type": "module",
   "exports": {
     ".": "./src/index.js",

{gammonview-2.0.0 → gammonview-2.0.2}/gvformat-js/src/constants.js

@@ -32,6 +32,8 @@ export const HEADER_FLAG_HAS_ANALYSIS = 0x0001;
 //   v3: the blanked bytes dropped -- checker record 7->3 B, cube record 6->2 B
 export const GVAN_VERSION = 3;
 
+// v1's cap on a decision's alternatives, used by `write_gvab_v1` only. v2
+// holds 1024 (`MAX_ALTS` in ogxm2_writer.js).
 export const MAX_ALTS_PER_DECISION = 50;
 
 // The largest hop a ply record can hold. A move step is one byte -- the start

{gammonview-2.0.0 → gammonview-2.0.2}/gvformat-js/src/legality.js

@@ -146,17 +146,19 @@ function extend(mine, opp, dice, acc, results) {
  * possible, and when a non-double allows only one die, the larger one must be
  * played if either alone is playable.
  *
- * @returns {{plays: Set<string>, diceUsed: number}} plays are normalizePlay keys.
+ * @returns {{plays: Set<string>, best: Array, diceUsed: number}} plays are
+ *   normalizePlay keys; best the maximal sequences they came from (empty in a
+ *   dance, which `isPlayLegal` relies on).
  */
 export function legalPlays(mine, opp, d1, d2) {
   const results = [];
   const dice = d1 === d2 ? [d1, d1, d1, d1] : [d1, d2];
   extend(mine, opp, dice, [], results);
-  if (!results.length) return { plays: new Set(), diceUsed: 0 };
+  if (!results.length) return { plays: new Set(), best: [], diceUsed: 0 };
 
   let longest = 0;
   for (const s of results) if (s.length > longest) longest = s.length;
-  if (longest === 0) return { plays: new Set(), diceUsed: 0 };
+  if (longest === 0) return { plays: new Set(), best: [], diceUsed: 0 };
 
   let best = results.filter((s) => s.length === longest);