@hexlabelposition/som 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladyslav Kudriashov
+
+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

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# som
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**som (SVG Object Model)** is a zero-dependency, tree-shakeable ESM toolkit for working with SVG as plain objects in any JavaScript runtime.
+
+> [!WARNING]
+> **Status: pre-alpha.** som is in the design phase, and every API shown below is a draft that may change. See [BACKLOG.md](./BACKLOG.md) for what is planned and [ARCHITECTURE.md](./ARCHITECTURE.md) for how it is built.
+
+## Why
+
+Working with SVG in JavaScript today usually means combining several packages: one to parse, one for paths, one for colors, one for bounds. Each has its own data format, its own types (or none), and often years without updates.
+
+som aims to replace them with one coherent toolkit built around a single document model.
+
+## Principles
+
+- **One library, one model.** Parse once, run any number of operations on the same tree, serialize once.
+- **SVG as plain objects.** The tree is ordinary data with no DOM nodes or parent references: edit it with plain property access, store it as JSON or send it to a worker.
+- **Lossless round trips.** Element order, text, comments, CDATA, processing instructions, the XML declaration, DOCTYPE, namespaces, attribute order, and unknown elements and attributes all survive `parse` → `stringify`.
+- **Type-safe.** Strict public types, including element and attribute types generated from the SVG specifications.
+- **Fast.** Single-pass parsing and minimal allocations, benchmarked against svgson and svg-parser. Published numbers come only from the benchmark suite.
+- **Zero dependencies.** Pure JavaScript with no runtime dependencies and no DOM requirement.
+- **ESM-only and tree-shakeable.** The API is made of independent functions without side effects, so a bundle contains only what you import: using `parse` does not pull in `stringify` or `colors`.
+
+## Guarantees
+
+- **Strict parsing.** Only well-formed XML is accepted, and every error has a stable code and a source position.
+- **Bounded parsing.** External entities are never loaded, and input size, nesting depth and entity expansion are limited.
+- **No implicit interpretation.** Attribute values stay strings until a module explicitly parses them.
+- **Tree-level round trips.** The tree is kept, not the exact source text: quote style, entity spelling and whitespace inside tags are normalized.
+
+## Planned features
+
+| Area                                   | What it covers                                                        | Planned for |
+| -------------------------------------- | --------------------------------------------------------------------- | ----------- |
+| **parse**                              | Parse SVG into an AST                                                 | v0.1        |
+| **stringify**                          | Serialize an AST back to SVG                                          | v0.1        |
+| **ast**                                | `clone`, traversal, queries, type guards                              | v0.1        |
+| **attributes**                         | Helpers for `style`, `class` and bulk attribute edits                 | v0.1        |
+| **spec types**                         | Element and attribute types per SVG version, generated from the specs | v0.2        |
+| **colors**                             | Extract, normalize and replace colors                                 | v0.3        |
+| **paths**                              | Parse, serialize and normalize path data (`d`)                        | v0.4        |
+| **geometry, transforms, optimization** | Bounds, lengths, matrices, cleanup                                    | later       |
+
+Versions show the intended order, not dates.
+
+## Usage (draft API)
+
+```ts
+import { parse, stringify, getRoot } from "@hexlabelposition/som";
+
+const doc = parse(
+  '<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="8"/></svg>',
+);
+const svg = getRoot(doc);
+
+// The tree is plain data: edit it directly.
+const circle = svg.children[0];
+if (circle.type === "element") {
+  circle.attributes.fill = "currentColor";
+}
+
+stringify(doc);
+// <svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="8" fill="currentColor"/></svg>
+```
+
+Operations mutate the document. When you need to keep the original, copy it explicitly:
+
+```ts
+import { clone } from "@hexlabelposition/som";
+
+const copy = clone(doc);
+```
+
+Malformed input throws an `SvgParseError` with a stable `code` and the `line`, `column` and `offset` of the problem.
+
+## Runtimes
+
+Node.js ≥ 22, Bun ≥ 1.2.23, Chromium, Firefox and WebKit, all tested in CI.
+
+## Non-goals
+
+som is **not** a JSX parser, a renderer, a visual editor, or a sanitizer. Parsed documents keep scripts, event handlers and external references, so a document from an untrusted source must not be injected into a page as is. som works with SVG/XML markup, not JSX.
+
+## Name
+
+**som** stands for **SVG Object Model**: SVG represented as a tree of plain objects. The project is called som; it is published on npm as `@hexlabelposition/som`, because the unscoped `som` name is taken.
+
+## Contributing
+
+The project is not open for contributions yet. Development setup and conventions are described in [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@hexlabelposition/som",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "Zero-dependency, tree-shakeable ESM toolkit for working with SVG as plain objects",
+  "keywords": [
+    "svg",
+    "ast",
+    "parser",
+    "serializer",
+    "xml"
+  ],
+  "homepage": "https://github.com/hexlabelposition/som#readme",
+  "bugs": "https://github.com/hexlabelposition/som/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hexlabelposition/som.git"
+  },
+  "license": "MIT",
+  "author": "Vladyslav Kudriashov",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "bun@1.4.0",
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "bun run build",
+    "typecheck": "tsc -p tsconfig.lib.json && tsc -p tsconfig.test.json && tsc -p tsconfig.scripts.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project node",
+    "test:browser": "vitest run --project browser",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check . '!**/*.md'",
+    "docs:check": "prettier --check '**/*.md'"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.5",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.20.5",
+    "@vitest/browser-playwright": "^5.0.5",
+    "eslint": "^10.13.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-boundaries": "^7.3.0",
+    "fast-check": "^4.10.2",
+    "jiti": "^2.7.0",
+    "playwright": "1.64.1",
+    "prettier": "^3.9.10",
+    "publint": "^0.3.25",
+    "tsdown": "^0.23.2",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.72.0",
+    "vitest": "^5.0.5"
+  }
+}