Naqsh · نقش

A review build for deterministic Arabic calligraphy avatars generated from the Arabic root of a seed's meaning. The visual style developed under the working name “Huruf Melt” is now Naqsh.

What is ready for review

• All 28 standard Arabic letters as portable SVG path assets.
• Isolated, initial, medial, and final presentation forms where joining applies.
• Lam–alef ligature handling.
• Arabic/Persian variant normalization and diacritic removal.
• Deterministic Arabic monograms for Arabic and non-Arabic seed strings.
• Context-aware English meaning → Arabic concept → three/four-radical root resolution.
• Direct Arabic lemma resolution, explicit root and sense overrides, and provenance metadata.
• Honest deterministic fallback for names or dictionary gaps; a fallback is never labeled as a linguistic root.
• Six palettes, three frame shapes, and one cohesive liquid-calligraphy style.
• Self-contained SVG output with no browser font dependency.
• A reproducible full-map compiler joining OEWN 2024, Arabic WordNet 4.1, and CAMELMORPH MSA.
• A DiceBear Core 10 / schema 1.2 style definition covering all 5,052 compiled roots through component banks and a semantic adapter.

This still stops before a public SDK release. The DiceBear-compatible review artifact is included now so the visual language and integration shape can be approved first.

Review locally

npm run check
python3 -m http.server 4173

Then open http://localhost:4173/review/.

The generated files are also directly inspectable:

• review/contact-sheet.svg — all 28 letters.
• review/semantic-root-sheet.svg — known meanings, an ambiguous sense, and fallback behavior.
• review/dicebear-sheet.svg — the same system rendered by official DiceBear Core.
• review/sample-sheet.svg — Arabic and arbitrary multi-letter seeds.
• review/letters/ — one 512px SVG per letter.
• review/samples/ — Arabic names and arbitrary string seeds.

Prototype API

import { renderAvatar, avatarDataUri } from './src/index.js';

const svg = renderAvatar('advance', {
  size: 512,
  shape: 'squircle',
  context: 'technology moving forward', // ق·د·م
  palette: 'lapis',
});

const payment = renderAvatar('advance', {
  context: 'salary advance payment', // س·ل·ف
});

const exact = renderAvatar('animation-project', { root: 'دحرج' });
const src = avatarDataUri('unlisted-handle'); // stable symbolic fallback

Supported review options:

Option	Values	Default
size	16–2048	256
shape	circle, squircle, square	squircle
rootStrategy	semantic, letters	semantic
context	text used to disambiguate a meaning	seed
sense	candidate ID, synset ID, or exact sense text	automatic
root	explicit 3- or 4-radical Arabic root	automatic
rootKey	explicit dictionary headword	automatic
rootMap	a huruf-root-map-v1 object	committed core map
letterCount	1, 2, 3 for symbolic/legacy output	3 semantic, 2 letters
palette	lapis, jade, plum, ember, sand, midnight	from seed
title	accessible SVG title	generic title

Inspecting a resolution is part of the API:

import { resolveSemanticRoot } from './src/index.js';

resolveSemanticRoot('advance', { context: 'advance notice' });
// { mode: 'semantic', root: 'سبق', arabicLemma: 'مسبق',
//   senseId: 'advance.prior', confidence: 0.97, ... }

DiceBear compatibility

dicebear/naqsh.json can be loaded directly by DiceBear Core 10. Use the included adapter when the root should reflect the resolved meaning rather than DiceBear's normal deterministic variant selection:

import { Avatar, Style } from '@dicebear/core';
import definition from './dicebear/naqsh.json' with { type: 'json' };
import { toDiceBearOptions } from './src/index.js';

const style = new Style(definition);
const options = toDiceBearOptions(
  'advance',
  { context: 'salary advance payment' },
  { size: 256 },
);
const svg = new Avatar(style, options).toString(); // سلف

See dicebear/README.md and the auditable dicebear/root-variants.json manifest.

Dictionary architecture

The browser review ships a small curated map so the visual bundle stays inspectable. scripts/build-root-map.py creates the full frozen map and a coverage manifest:

1. read every Open English WordNet 2024 headword and sense;
2. join it to Arabic WordNet 4.1 by the shared synset ID;
3. attach a morphological root from CAMELMORPH MSA's Arabic lemma table and compile a direct Arabic lemma index;
4. use exact CAMELMORPH English glosses as a secondary route;
5. keep an empty entry for unresolved dictionary words, which must use symbolic fallback.

This gives stable, versioned behavior without a runtime translation API. It does not claim that every spelling has one objectively correct root: meanings are sense-specific, proper names may have no lexical root, and some Arabic roots contain four radicals.

The committed build covers all 151,630 normalized OEWN dictionary keys: 43,812 currently have 133,479 attested sense/root candidates, while 107,818 keys are intentionally marked for symbolic fallback. It also indexes 26,216 Arabic lemmas directly. See data/root-map.v1.manifest.json for the reproducible coverage record.

With source checkouts at the default ../references paths:

npm run build:roots
npm run roots:inspect -- advance

Node applications can gunzip data/root-map.v1.json.gz, parse it, and pass that object as rootMap. The eventual SDK can package that loading step separately from the renderer.

Rebuilding glyph assets

The committed generated paths are sufficient to run the project. Regeneration additionally requires an Amiri checkout at ../references/amiri/fonts/Amiri-Regular.ttf and Python fontTools:

npm run build:glyphs

Amiri is licensed under the SIL Open Font License 1.1. See THIRD_PARTY.md and vendor/Amiri-OFL.txt.

Architectural references

• DiceBear: keyed deterministic resolution and separable style assets.
• Facehash: a small seed-to-SVG product surface.

Naqsh's artwork and combination logic are original. See DESIGN.md for the semantic policy, visual rationale, and deferred SDK work.