@urbit-xyz/azimuth-hanzi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 azimuth-hanzi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# azimuth-hanzi
+
+Chinese-character sigils for Urbit Azimuth identities. Maps the 512 Urbit syllables (256 prefixes + 256 suffixes) to Hanzi characters and renders them as SVG.
+
+> **Status:** the mapping is a work in progress. This repository is open so the character assignments can be refined collaboratively before they are finalized. See [DESIGN.md](./DESIGN.md) for the ruleset and open items.
+
+## Install
+
+```bash
+npm install @urbit-xyz/azimuth-hanzi
+```
+
+## Use
+
+```typescript
+import { hanziSigil, parsePoint } from '@urbit-xyz/azimuth-hanzi'
+
+const svg = hanziSigil({
+  point: '~sampel-palnet',
+  size: 128,
+  background: '#000',
+  foreground: '#fff',
+  space: 'default', // 'none' | 'default' | 'large'
+})
+
+const parsed = parsePoint('~sampel-palnet')
+// { phonemes: ['sam', 'pel', 'pal', 'net'], characters: ['森', '培', ...], type: 'planet' }
+```
+
+Layout by point type:
+
+| Ship type | Characters | Layout       |
+| --------- | ---------- | ------------ |
+| Galaxy    | 1          | Centered     |
+| Star      | 2          | Side-by-side |
+| Planet    | 4          | 2×2 grid     |
+| Moon      | 8          | 2×4 grid     |
+
+For repeated renders of the same configuration, use `memoizedHanziSigil` (same signature, cached by config).
+
+### Web components
+
+Auto-registered on module load:
+
+```html
+<urbit-hanzi point="~sampel-palnet" size="128" background="#000" foreground="#fff"></urbit-hanzi>
+<urbit-hanzi-image point="~sampel-palnet" size="128"></urbit-hanzi-image>
+```
+
+### Inspecting the mapping
+
+```typescript
+import { PREFIXES, PREFIX_GROUPS, getCharacter } from '@urbit-xyz/azimuth-hanzi'
+
+PREFIXES[0]                      // 'doz' — Urbit syllable for byte 0
+getCharacter('doz')              // '红' — assigned Hanzi
+PREFIX_GROUPS['Colors & Light']  // { 0: ['红', 'hóng', 'red'], 1: ['青', 'qīng', 'azure'], ... }
+```
+
+`SUFFIXES`, `SUFFIX_GROUPS`, `PREFIX_CHARACTERS` (flat map with category attached), `PHONEME_INDEX`, `isPrefix`, and `isSuffix` are also exported.
+
+## Develop
+
+```bash
+git clone https://github.com/master-malwyl/azimuth-hanzi
+cd azimuth-hanzi
+npm install
+npm run build    # emits ./dist
+npm test
+npm run preview  # serves http://localhost:8080/preview.html
+```
+
+`preview.html` is a single-file catalogue viewer: every prefix and suffix side-by-side with pinyin and gloss, plus a generator that renders any Urbit ID.
+
+## Contributing
+
+Read [DESIGN.md](./DESIGN.md) first — it explains the goal, the ruleset that guides character choices, and the open items a refinement pass should tackle.
+
+The canonical 512-character mapping lives in [`src/mapping.ts`](./src/mapping.ts), keyed by byte (0–255) and grouped by theme:
+
+```typescript
+export const PREFIX_GROUPS = {
+  'Colors & Light': {       // bytes 0-21 (doz..lid)
+    0:  ['红', 'hóng', 'red'],
+    1:  ['青', 'qīng', 'azure'],
+    // ...
+  },
+  // ...
+}
+```
+
+To change an assignment, edit the `[character, pinyin, gloss]` tuple in place. The group key is the category; moving an entry to a different category means moving the line to a different group (and updating the byte-range comment on both groups).
+
+Open a PR explaining which rule from DESIGN.md the change advances.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).