paperdoll

paperdoll is a small TypeScript protocol library for modeling body-like containment graphs: rooted arrangements of vessels connected by directional ports, with typed compatibility tokens, contained elements, recursive embedded bodies, and deterministic derived layout.

It has no runtime dependencies and does not include a renderer. Presentation concerns such as labels, icons, colors, typography, node sizing, and canvas controls belong to consumers.

Install

npm install paperdoll

Minimal Document

import { PAPER_DOLL_PROTOCOL, parseDocument, deriveLayout } from "paperdoll";

const document = {
  protocol: PAPER_DOLL_PROTOCOL,
  body: {
    root: "body",
    vessels: {
      body: {
        accepts: [{ kind: "item", type: "body" }],
        contains: [{ kind: "item", type: "body", id: "jacket" }],
        ports: {
          top: { vessel: "head", side: "bottom" }
        }
      },
      head: {
        accepts: [{ kind: "item", type: "hat" }],
        ports: {
          bottom: { vessel: "body", side: "top" }
        }
      },
      floating: {
        accepts: [{ kind: "item", type: "floating" }],
        contains: [{ kind: "item", type: "floating", id: "glowsphere" }]
      }
    }
  }
};

const parsed = parseDocument(document);
if (!parsed.ok) throw new Error(parsed.errors[0].message);

const layout = deriveLayout(parsed.value.body);
console.log(layout.figure.body); // { x: 0, y: 0 }
console.log(layout.figure.head); // { x: 0, y: -1 }
console.log(layout.free); // ["floating"]

The Model

A body is a set of named vessels with one distinguished root. A vessel is a container with optional compatibility declarations (accepts), optional contents (contains), and optional connection faces (ports).

• The figure of a body is the connected component of the root. It gets deterministic abstract coordinates.
• A vessel outside the figure with no ports is a free vessel (what a consumer might call a pool, an aura, cargo, or "nearby"). Free vessels are reported as a sorted list without coordinates; where to draw them is a renderer decision.
• A vessel outside the figure with ports is invalid.

An element is a thing contained: { kind, type?, id?, data?, body? }. It is opaque to the protocol except for its typed envelope — and except when it embeds a body, which the protocol validates recursively. A backpack is an element and a body.

Laws

Validity is the conjunction of eight laws, applied recursively to every embedded body:

1. Rootedness — root names an existing vessel.
2. Reciprocity — every port is reciprocated by its target.
3. Opposition — ports connect only opposite faces (top↔bottom, left↔right).
4. Planarity — derived figure coordinates are collision-free and consistent.
5. Reachability — every ported vessel is in the figure.
6. Compatibility — in a vessel that declares accepts, every contained element matches at least one accept token. Absent accepts is open; accepts: [] is sealed.
7. Recursive validity — every embedded body is itself valid.
8. Identity — element ids, where present, are lowercase ids unique within their vessel. Elements without ids are legal but unaddressable.

Matching is purely structural: a token { kind, type? } matches an element when kinds are equal and the token's type, if present, equals the element's type. The protocol never interprets what a kind means.

Addressing

Law 8 makes stable addresses possible. An address is a /-separated path of lowercase ids, alternating vessel and element segments, descending through element.body:

import { resolveAddress } from "paperdoll";

resolveAddress(body, "left-hand");                        // { kind: "vessel", ... }
resolveAddress(body, "left-hand/steel-dagger");           // { kind: "element", index, element }
resolveAddress(body, "back/field-pack/main-pocket/rope"); // descends into the pack's own body

resolveAddress returns null for addresses that don't resolve and throws on malformed input. Addresses are stable under contains reordering — they name elements by id, never by index — which is what sibling protocols (paperchain scenes, paperfold patches) rely on.

Editing Bodies

import { connect, insertVessel, insertElement, moveElement } from "paperdoll";

// grow the figure: bridge a new vessel into an existing connection
const { body: withElbow, vesselId } = insertVessel(body,
  { accepts: [{ kind: "item", type: "arm" }] },
  { at: { vessel: "body", side: "right" }, id: "elbow" }
);

// or create a free vessel
const { body: withCargo } = insertVessel(body, { accepts: [{ kind: "item", type: "cargo" }] });

// containment is law-checked at the door
const stocked = insertElement(withElbow, "elbow", { kind: "item", type: "arm", id: "prosthetic" });
insertElement(withElbow, "elbow", { kind: "item", type: "hat" });
// throws: Element "item/hat" is not accepted by vessel "elbow".

// moves are atomic: the destination is checked before removal
const swapped = moveElement(body, "left-hand", 0, "right-hand");

All editing helpers return new objects and do not mutate their inputs. Destructive and overwriting operations additionally return what they removed, so every edit can be undone without diffing:

const { body: severed, vessel, collapsed } = deleteVessel(body, "left-lower-arm");
// vessel: the deleted vessel exactly as it was (accepts, contains, ports)
// collapsed: the neighbor connection created by collapseOppositeNeighbors, or null

const { body: cut, removed } = disconnect(body, { vessel: "feet", side: "right" });
// removed: the severed connection, or null if the port was empty

const { body: wired, displaced } = connect(body, from, to);
// displaced: any prior connections (0-2) that the new one overwrote

Operations enforce local laws (existing endpoints, opposition, no self-connections, compatibility) and throw on violation; graph-global laws (planarity, reachability) are checked by parseDocument / validateDocument, which callers run after a batch of edits — legitimate multi-step edits pass through globally incomplete states.

Migrating from v1

Legacy documents are rejected by the v3 parser with errors pointing at the right migration:

import { migrateV1, migrateV2 } from "paperdoll";

const fromV1 = migrateV1(v1Document); // slots+pools -> vessels, port addresses rewritten
const fromV2 = migrateV2(v2Document); // protocol string bump + law 8 validation

Both return Result values. Migration is strict: a v1 document whose contents violate its own accepts (law 6), or a v2 document with duplicate or non-lowercase element ids (law 8), fails with precise error paths rather than being silently repaired.

Portability

The protocol is the document format plus the laws in the current normative paper-doll/v3 specification. schema/paper-doll-v3.schema.json is its structural JSON Schema (2020-12) companion, not a complete specification. Package versions and sibling dependency floors are listed in the paper* family compatibility matrix. Any language can validate paperdoll documents. (The v2 schema remains in schema/ as a historical artifact.)

For interchange through implementations that parse JSON numbers as IEEE 754 binary64, the optional paper-json-portable/v1 profile requires finite numbers and limits integral values to ±9007199254740991. validatePortableJson(value) checks the complete value recursively without changing dialect validity. It cannot recover a numeric token rounded before validation; encode larger exact integers as canonical decimal strings under an application field contract.

API

• constants: PAPER_DOLL_PROTOCOL, SIDES, OPPOSITE_SIDES, MAX_PORTABLE_INTEGER
• validation: parseDocument, assertDocument, validateDocument, validatePortableJson, formatProtocolErrors
• piecemeal validation (for sibling protocols embedding kernel fragments): isId, validateKnownKeys, validateEndpoint, validateConnection, validateAcceptToken, validateContainedElement
• migration: migrateV1, migrateV2
• addressing: parseAddress, resolveAddress
• graph/layout: deriveConnections, deriveLayout
• compatibility queries: matches, isAccepted
• topology operations: connect, disconnect, insertVessel, deleteVessel
• containment operations: insertElement, removeElement, moveElement
• types: AcceptToken, Body, ContainedElement, DerivedLayout, Endpoint, JsonValue, PaperDollDocument, Vessel, VesselId, Side, and related helper types

Validation is strict: unknown keys anywhere in a document are rejected, so presentation or game data cannot ride along inside protocol documents. Attach consumer data through ContainedElement.data (which is opaque to the protocol, always) or keep it outside the document keyed by vessel id. parseDocument returns a deep copy of its input.

The paper* Family

paperdoll is the kernel of a four-protocol family. Each sibling answers a different question about bodies, imports the kernel, and never reaches into its internals:

• paperdoll — is this arrangement of vessels lawful? The eight laws, the address grammar, the pure operations. This library.
• paperchain — how do bodies relate to each other? Scenes: flat, typed, geometry-free relations between addresses across bodies (two paper dolls holding hands).
• paperfold — how did a body change? Patches: diff, apply, compose, invert — change itself as a value, with laws.
• papermold — is this body a valid instance of some kind? Profiles: structural conformance judged against consumer-authored stencils ("is this really mech-shaped?").

The historical design record lives in this repo: the RFCs under docs/ and the transcript capture the discussions that produced the family. They are not normative specifications.

Design Notes

See the current paper-doll/v3 specification for normative behavior. docs/core-ontology.md, docs/rfc-vessel-calculus.md, the sibling RFCs, and the transcript are historical design records.