@johnmorrisdotca/kumimoji 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -6,6 +6,53 @@ All notable changes to this project are written down here. The format follows
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-09-30
+
+Nothing that was exported has changed, a seed deals the bag it always dealt,
+and the word lists and how they load are as they were.
+
+### Added
+
+- **Export and import.** `kumimojiToJSON` writes a game alone as versioned
+  JSON (`"format": 1`): how it was set up, its seed and where the player has
+  got to. `kumimojiFromJSON` reads it back by dealing the bag again from the
+  seed and checking every tile held against it, so nothing in a file is
+  trusted. `kumimojiToText` is a game as plain text and `gridToText` a
+  crossword as it lies. `kumimojiExported`, `kumimojiClock`,
+  `KUMIMOJI_EXPORT_FORMAT`, `KumimojiSaved` and `KumimojiExported` with them.
+- **The table's words in English and Japanese**, in one table,
+  `KUMIMOJI_STRINGS`, listed side by side in `docs/strings-ja.md`.
+  `mountKumimoji` takes `locale` and `strings`, follows the page's `lang`, and
+  its handle has `setLocale`. `kumimojiStrings`, `kumimojiSay`,
+  `KumimojiStrings` and `KumimojiLocale`. The Japanese has not yet been
+  reviewed by a native reader.
+- **Saving and loading on the table**: save as JSON or as text, and load a
+  saved game back with its clock going on. `keep: false` leaves it off; the
+  handle has `saved` and `setGame`, and the table takes `onChange`.
+- **Theming.** `--km-radius` and `--km-font` beside the colours, and
+  `mountKumimoji` takes a `theme`.
+- `KUMIMOJI_VERSION`.
+- A doc comment on every export, held by a test.
+- The README says near its top, and in a section of its own, what each word
+  list is, where it came from and under what terms: SCOWL's permissive
+  licence, and CC BY-SA 4.0, attribution and share-alike, for the list derived
+  from JMdict.
+- The demo in the family's look, in English and Japanese, a game kept on the
+  device between visits.
+- Checks: the package packed by npm, installed in an empty project, every
+  entry imported and required, both lists read and their notices found in the
+  tarball, on Linux, macOS and Windows; every example in the README run; the
+  table tapped in Chromium and WebKit; and the table built and played in
+  React, Vue, Svelte, Angular and a plain page.
+
+### Changed
+
+- A square and a tile on the table are 44px, from 36px, and every button is
+  at least 44px: a fingertip. `--km-square` sets another size.
+- `package.json` has `main`, `module` and `types` beside `exports`, for tools
+  that read those.
+- `--km-apart`, which nothing used, is no longer defined.
+
 ## [1.0.1] - 2026-09-30
 
 ### Fixed
@@ -47,7 +94,8 @@ The first release.
   `@johnmorrisdotca/kumimoji/react`.
 - A static demo for GitHub Pages.
 
-[Unreleased]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.0.1...HEAD
+[Unreleased]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/johnmorrisdotca/kumimoji/releases/tag/v1.1.0
 [1.0.1]: https://github.com/johnmorrisdotca/kumimoji/releases/tag/v1.0.1
 [1.0.0]: https://github.com/johnmorrisdotca/kumimoji/releases/tag/v1.0.0
 [0.1.0]: https://github.com/johnmorrisdotca/kumimoji/commits/v1.0.0

package/CONTRIBUTING.md

@@ -1,38 +1,83 @@
 # Contributing to Kumimoji
 
-Thank you for wanting to help. Bug reports, rule questions and pull requests are
-all welcome.
+Thank you for helping. Bug reports, rule questions, corrections to the
+Japanese and pull requests are all welcome.
 
 ## Reporting a bug
 
-Open an [issue](https://github.com/johnmorrisdotca/kumimoji/issues) with what you did,
-what you expected and what happened. A game's seed makes almost any bug
-reproducible: include it, and the moves if you have them.
+Open an [issue](https://github.com/johnmorrisdotca/kumimoji/issues/new?template=report-a-bug.md)
+with what you did, what you expected and what happened. A seed deals the same
+bag every time, so the table's *Save as JSON* file, or the seed with the
+language, hand and level, makes almost any bug reproducible.
 
 ## Making a change
 
 ```sh
-git clone https://github.com/johnmorrisdotca/kumimoji.git
+git clone https://github.com/johnmorrisdotca/kumimoji
 cd kumimoji
 pnpm install
-pnpm run check    # lint, types and tests, as CI runs them
-pnpm run site     # build the demo into site/ and open site/index.html
+pnpm check            # lint, types and tests: the same as CI
+pnpm test:table       # the demo in real browsers: builds it, then taps it
+pnpm test:package     # npm pack, install the tarball, import and require every entry, read both lists
+pnpm test:frameworks  # the README's examples built in React, Vue, Svelte, Angular and a plain page
+pnpm site             # builds the demo into ./site
+pnpm dlx serve site   # or any static server
 ```
 
-- The rules are pure functions over plain values: a function returns a new
-  game and never changes the one it was given. Keep it that way.
-- Anything random is drawn from the game's own seeded random, so a game always
-  replays from its seed. Never call `Math.random` inside the rules.
-- Add or change a test beside the code you change (`*.test.ts`).
-- Note the change under **Unreleased** in [CHANGELOG.md](CHANGELOG.md).
-- Keep pull requests to one change each, with a message that says what a player
-  or a developer would notice.
+- **The rules are pure.** Everything outside `src/ui` and `src/react.tsx` is
+  plain functions over plain data, with no DOM and no dependency. A function
+  returns a new game and never changes the one it was given.
+- **Never break a seed.** Anything random is drawn from the game's own seeded
+  random, never from `Math.random`, and a seed must deal the bag it always
+  dealt, because people race them. `scripts/check-package.mjs` pins two.
+- **Nothing read is trusted.** A game read back (`kumimojiFromJSON`,
+  `decodeTileProgress`, `decodeParty`) is checked against its own bag.
+- **The word lists are other people's, and their notices travel with them.**
+  `src/words.en.data.ts` is made from SCOWL and `src/words.ja.data.ts` from
+  JMdict; neither is edited by hand, each opens with its notice, and
+  `NOTICE.md` has both in full. JMdict's list is under CC BY-SA 4.0:
+  share-alike. A change that adds a list, swaps one, or drops a notice is not
+  a small change: open an issue first. A new list comes from a real
+  dictionary of its language, with a licence that lets its words be shipped,
+  and its terms go in `NOTICE.md` and the README in the same change.
+- **How the lists load is not to be changed lightly.** They are fetched by a
+  dynamic import behind `typeof window`, so that a page's server code never
+  carries them; Itsutsu relies on it.
+- **Test what you change.** Tests sit beside their source as `*.test.ts`.
+- **The table is tested by tapping it.** `table/*.table.mjs` are Playwright
+  tests that open the built demo in Chromium and WebKit, at a phone's width by
+  touch and at a desktop's by mouse, and do what a person does. After every
+  flow they check that nothing is wider than the screen, nothing to tap is
+  under 44px, and the page complained of nothing. The first time,
+  `pnpm exec playwright install chromium webkit` fetches the browsers.
+- **Words go in `src/strings.ts`**, in English and Japanese, then
+  `pnpm docs:make` to bring `docs/strings-ja.md` up to date. Japanese is plain
+  and polite, and uses the words players use: タイル, 手札, 袋, ワイルド.
+- **Examples in the README are run.** `src/docs.test.js` runs every
+  TypeScript example and checks each value it states (a line ending
+  `// → value`); `scripts/check-frameworks.mjs` takes the React, Vue, Svelte,
+  Angular and plain-page examples from the README as they are written, builds
+  each from the packed tarball and lays a tile.
+- **Every export gets a doc comment**, which a test holds, and the README's
+  tables (options, theming, limits) are checked against the code.
+- **The demo wears the family's look.** `demo/family.css` is the same file in
+  every sibling package's demo, and a test fails if it differs from its
+  recorded hash. What is Kumimoji's own goes in `demo/kumimoji.css`.
+- **No dependencies.** The package has none at run time and should stay so.
+- **No name, art or wording of a published game.**
+- One change per pull request, with a line in `CHANGELOG.md` under
+  *Unreleased*.
 
 ## Releasing
 
-Maintainers bump the version in `package.json`, move **Unreleased** in the
-changelog under the new version and date, tag `v<version>`, and publish with
-`pnpm publish --access public`.
+Maintainers bump the version in `package.json` and `src/version.ts` and move
+*Unreleased* to the new version in `CHANGELOG.md`, dated. Pushing the tag
+`vX.Y.Z` runs the Release workflow, which checks that the tag matches
+`package.json`, runs the checks, builds the package, installs and uses it as
+npm packs it, attaches the tarball to a GitHub release, and publishes it to
+npm with provenance, through npm's trusted publishing (no token is kept). A
+version already on npm is not published again. The workflow can also be run
+by hand.
 
-By contributing you agree that your work is released under the
+By contributing you agree that your code is released under the
 [MIT licence](LICENSE), and to follow the [code of conduct](CODE_OF_CONDUCT.md).