compasso 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Canô
+
+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,123 @@
+# compasso
+
+Standards-faithful relational diagrams as **pure SVG strings**. Deterministic, zero
+runtime dependencies, server-safe (no DOM, no canvas, no clock, no randomness).
+
+**v0.1 ships two clinical diagrams:** the **genogram** (McGoldrick family-systems
+notation) and the **ecomap** (radial person↔environment ties). The architecture is
+built for more — see the roadmap.
+
+## Principles
+
+- **Pure data → string.** Every renderer is a pure function: same input, same SVG,
+  in any runtime (browser, Node, edge, tests).
+- **Honesty rule.** The diagram presents only what the caller declared — no synthesized
+  structure (two declared parents without a declared union never merge into a couple),
+  no interpretation (a line style is a conservative lexical hint from the author's own
+  words; ambiguity abstains to neutral). Verbatim text always rides each element's
+  `<title>`.
+- **Overlap-proof by construction.** The genogram layout is a grid of columns, rows,
+  gutters and corridors with lane allocation — labels and routed lines cannot collide,
+  and a test harness proves it on every commit. No diagonals, no text on edges.
+- **Embedder-safe output.** Numeric `width`/`height` + matching `viewBox`, literal
+  presentation attributes (no CSS classes, no `currentColor`, no `<marker>` defs),
+  XML-escaped everywhere — safe for `innerHTML` and for SVG-to-PDF pipelines.
+- **Localizable.** English defaults; vocabularies (labels, kinship words, quality
+  lexicons) are injectable packs. `compasso/locales/pt-br` ships Brazilian Portuguese.
+
+## Install
+
+```sh
+pnpm add compasso
+```
+
+## Genogram
+
+```ts
+import { genogramSvg } from "compasso/genogram";
+
+const { svg } = genogramSvg({
+  people: [
+    { id: 1, label: "my mother", sex: "female", deceased: false, generation: -1 },
+    { id: 2, label: "my father", sex: "male", deceased: true, generation: -1 },
+    { id: 3, label: "me", sex: "unknown", deceased: false, generation: 0 },
+  ],
+  unions: [{ id: 1, personAId: 1, personBId: 2, status: "divorced", quality: null }],
+  parentLinks: [
+    { id: 1, parentId: 1, childId: 3, quality: null },
+    { id: 2, parentId: 2, childId: 3, quality: "distant for years" },
+  ],
+  relationships: [],
+});
+```
+
+Union statuses: `married | cohabiting | dating | separated | divorced | coparental |
+unknown` — each drawn with its McGoldrick notation (solid bar, dashed bar, one slash,
+two slashes). A `coparental` union draws **no couple element** at all: the
+co-parenthood shows only on the descents converging on the child.
+
+Free-text `relationships` are classified conservatively: derived kinship words
+(sibling, grandparent, uncle…) draw **nothing** (the tree already implies them), direct
+parentage words may be **promoted** to a dotted descent oriented by declared
+generation, everything else stays a non-structural bond line. People left with no
+drawn connection are grouped and labeled, never floated silently.
+
+Lower-level entry points: `computeGenogramLayout` (pure layout: nodes, routed
+orthogonal elements, traceable `data-edge-id`s) and `genogramLayoutSvg` (layout →
+string), for callers that decorate, hit-test, or post-process.
+
+## Ecomap
+
+```ts
+import { ecomapSvg } from "compasso/ecomap";
+
+const svg = ecomapSvg({
+  centerLabel: "Me",
+  ties: [
+    { id: 1, label: "work", quality: "draining", direction: "out" },
+    { id: 2, label: "church", quality: "very close", direction: "in" },
+    { id: 3, label: "neighbors", quality: null, direction: null }, // neutral line, no arrow
+  ],
+});
+```
+
+Arrowheads appear **only** for a declared `direction` (`"in"` toward the center,
+`"out"` toward the system, `"both"`); `null` draws no arrow — never a default. Large
+sets split onto two alternating rings; node spacing is overlap-proof by construction.
+
+## Localization
+
+```ts
+import { genogramSvg } from "compasso/genogram";
+import {
+  GENOGRAM_SVG_LABELS_PT_BR,
+  GENOGRAM_TITLE_LABELS_PT_BR,
+  KINSHIP_PT_BR,
+  QUALITY_LEXICON_PT_BR,
+} from "compasso/locales/pt-br";
+
+genogramSvg(input, {
+  kinship: KINSHIP_PT_BR,
+  qualityLexicon: QUALITY_LEXICON_PT_BR,
+  titleLabels: GENOGRAM_TITLE_LABELS_PT_BR,
+  svgLabels: GENOGRAM_SVG_LABELS_PT_BR,
+});
+```
+
+A locale pack is plain data — labels, whole-word kinship tokens, quality-word needles
+with a negation list. PRs for new locales are welcome.
+
+## Roadmap
+
+The goal is a family of standards-faithful technical diagrams sharing this core
+(text metrics, stroke vocabulary, escaping, legend machinery): tree-based diagrams
+(fault tree, phylogenetic, fishbone), flow/layered diagrams (PRISMA, UML), and
+symbol-library diagrams (P&ID, single-line, ladder logic) — each built from its public
+standard. AST-first; text DSLs may come later.
+
+## Provenance & license
+
+MIT © Victor Canô. The genogram engine descends from a production renderer the author
+wrote for a clinical intake product (same copyright holder); the ecomap renderer is
+original to this repository. Developed independently of any third-party diagram
+engine's code.