Kickoff handoff

priyome (Russian, chess) — a standard method or technique. A common move, plan, or pattern that experienced players recognize and reuse.

This document seeds a future kickoff session. Priyome doesn’t exist yet beyond this folder; it’s an idea worth doing carefully, and that session is where the real design work starts. Read this for context, then we’ll dig in.

What Priyome is

A sibling project in the chess workspace, parallel to Motif:

Motif ships components for building chess applications (Lichess / Chess.com / TNMP-shaped UIs — panels, full-pane MoveLists, EnginePanels, app-shell-aware components).
Priyome ships components for embedding chess as web content — inline diagrams, clickable move references in prose, compact widgets that drop into any HTML document.

The thesis: chess data is a first-class web content type, like images or code snippets, and the library that treats it that way enables an entirely new category of chess-aware content.

Audience extends beyond chess-app developers to anyone embedding chess in documents: bloggers, book authors, educators, course creators, content platforms, static-site authors, anyone writing prose where chess deserves to be interactive rather than just visible.

Why it’s separate from Motif (not a Motif extension)

The two libraries share underlying infrastructure (Tabia for data, Rabbit for board rendering) but have genuinely different theses, audiences, and consumption shapes:

	Motif	Priyome
Thesis	Build polished chess apps fast	Make chess data first-class web content
Consumer	Chess app developers	Anyone embedding chess in documents
Shape	Panel-sized components	Inline-sized components
State	Rich, persistent (sessions, routing)	Stateless or minimally stateful
Distribution	npm + bundler	Probably CDN-friendly, drop-in script
Polish target	Coherent app experience	Fit gracefully into host’s design
Layout assumption	Owns its viewport region	Lives inside arbitrary DOM context

Bundling these into one library would force compromises on both sides. Motif’s API would double; Priyome’s components would inherit Motif’s panel-shaped baggage. Separate projects keep each thesis clean.

The workspace already supports this — adding a fourth sibling has roughly zero incremental cost.

Motivating examples

Concrete use cases that drove the design discussion:

1. The prep reader. A tool for reading opening books (Avrukh, Kaufman, etc.) where the page is mostly prose with embedded chess content. Hundreds of inline move references per chapter; dozens of diagrams; the reader needs an integrated experience where moves in the text and the viewer’s current position stay in sync.

2. reference-tree. A workspace project for navigating opening reference trees from PDF books. Similar shape: prose with chess-aware annotations, cross-references, position bookmarks.

3. Chess.com-style blog articles, but interconnected. Chess.com solved “embed a game in a blog post” — each widget is a self-contained mini-app. What’s unsolved is making the prose itself chess-aware: clickable move references in surrounding text, position pills that pop out diagrams, scroll-position sync with a primary viewer. The chess content stops being isolated embeds and becomes an interconnected reading experience.

4. Educational content. Courses, lessons, puzzle articles, tutorials — anywhere a teacher or content creator wants chess to be a participatory medium in their writing.

5. Hand-authored HTML pages. A user writing a personal site or blog post adds <priyome-diagram fen="..." /> and gets a working chess diagram without setting up a build pipeline.

Component categories explored

Five rough categories emerged. Naming prefix here is illustrative (priyome-) but not committed.

1. Inline visual primitives

Embeddable in flowing content. The HTML-element analogues for chess data.

priyome-diagram — inline static board for a FEN, optional arrows/squares. The <img> for chess positions.
priyome-line — inline move sequence as text, each move clickable, hover preview. The code-snippet for chess.
priyome-figurine — single-move figurine rendering (replacing “Nf3” with a knight icon + “f3”). Useful for prose-heavy chess writing.
priyome-position-pill — tiny clickable badge representing a position; expands to a diagram on click/hover. The <abbr> for chess.

2. Compact interactive widgets

Fit in a sidebar, margin, or inline figure — not a full pane.

priyome-mini-viewer — compact game viewer (~300×400px). Board + step controls + move readout, blog-friendly.
priyome-position-stepper — fixed board with prev/next buttons walking through a sequence. Teaching diagrams.
priyome-puzzle-card — a position + “your move” affordance, embeddable as a card in any layout.

3. Coordination primitives

Render nothing themselves; make other components work together.

priyome-game-context — wraps a region of the page; child widgets that need shared chess state subscribe to it. Multiple inline diagrams + a viewer + move-refs in prose all coordinate via this container.
priyome-position-cursor — virtual cursor tracking “the current position” across many widgets. Updates when the user clicks a move ref, scrolls past an anchor, navigates the board, etc.
priyome-line-anchor — declarative chess-content anchor in prose; as the reader scrolls past it, the page-level board updates. Reading-position binder.
priyome-move-ref — inline move reference (in prose) that drives its containing game-context. <a href> for chess moves.

4. Authoring / capture primitives

For apps where the user creates chess content.

priyome-position-editor — drag pieces onto a board to set up a position. No move legality, no engine; pure position authoring.
priyome-move-recorder — capture moves as the user makes them.
priyome-annotation-input — comment/NAG/arrow input with chess-aware shortcuts.

5. Declarative data sources

Provide data; other components consume it.

priyome-fen-source — declarative provider of a FEN, referenceable by name.
priyome-pgn-source — same for PGNs.
priyome-game-library — named collection of games available to the page.

The chess.com comparison (the canonical worked example)

The chess.com blog article we looked at — an article about chess “domination” with embedded Kasparov-vs-Shirov game viewer — is the perfect baseline. It shows the ceiling of the existing approach: a polished, self-contained widget embedded as a block in prose.

What chess.com does:

Each chess viewer is a self-contained mini-application
Prose around it is plain text
Move references in the prose (“17. Rxb7!?”) aren’t clickable; reader has to mentally translate to “scroll up, click forward N times in the widget”
Concept words (“blockade”, “exchange sacrifice”) have no inline previews
Multiple widgets on the page don’t share state

What Priyome enables:

The same article, but every move reference is a priyome-move-ref that navigates the embedded viewer
Concept words have priyome-position-pill previews
The whole article wraps in a priyome-game-context so widgets coordinate
Reading flow is continuous; no widget-context-switching

This isn’t a small UX improvement — it’s a categorical change in what chess writing on the web can be.

Architectural constraints (what makes content primitives different)

Every Priyome component should satisfy three properties that Motif’s panel-shaped components don’t:

Embeddable in any DOM context. Works in a <p>, an <article>, a <table>, a <figcaption>. Doesn’t demand a viewport region; inline- block-friendly. Author can drop it inside any HTML structure.
Stateless or minimally stateful. Reads from external state (via priyome-game-context or its own attributes) and renders. Doesn’t manage sessions; doesn’t persist preferences. Coordination is via parent context, not internal state.
Coordinates via declarative anchors, not imperative wiring. Multiple widgets cooperate by referring to the same game-context, not by the consumer writing event handlers. The author writes HTML; the wiring is the parent containment.

These constraints sound like restrictions but are actually what enable the “drop into any document” property. Motif components break all three; that’s fine for chess apps, fatal for content primitives.

What’s shared with Motif (the workspace foundation)

Priyome doesn’t reinvent chess logic. It consumes the same foundations:

Tabia — chess data layer (PGN parser, Game factory, identity hashing, merge, ReplayEngine). Priyome components are display+coordination shells over Tabia.
Rabbit (or chessground, via Tabia’s renderer-adapter contract) — board rendering. Priyome doesn’t render boards itself.
Action vocabulary — if Motif establishes a shared action vocabulary (copy, flip, play, etc.), Priyome’s buttons participate in the same protocol. Same <motif-button action="copy"> works in a Priyome viewer.
Design tokens (probably) — Priyome components want Motif-flavored defaults but must respect the host page’s design when overridden. Token inheritance with override-friendly cascading.

What’s NOT shared:

Motif’s panel-shaped components (they don’t fit Priyome’s context)
Motif’s app-shell assumptions (Priyome lives in someone else’s page)
Motif’s distribution model (Priyome wants CDN-friendly, no-build use)

Open questions for the kickoff session

These are the design decisions worth nailing carefully:

Tag prefix. priyome-*? p-*? Something more semantically chess-y? Affects every component’s name; worth deliberation.
Distribution model. Pure ESM via CDN? Bundled custom-elements registry? Drop-in <script> tag? Multiple targets? How does a non-developer (bookmark-and-paste user) install this?
Framework target. Vanilla web components? Lit (to match Motif)? Stencil for build-time optimization? Astro components for static-first? Maybe multiple, with a shared core.
Static site generator / MDX integration. What’s the story for embedding in MDX, Astro, Eleventy, Hugo, etc.? Markdown extensions? Shortcodes?
Theming inheritance. How do components inherit from the host page’s CSS while still being recognizably Priyome by default? CSS custom properties with sensible fallbacks?
Minimum v0 surface. Which 4–6 components ship first? My intuition: diagram, mini-viewer, game-context, move-ref. Enough to make the prep-reader and a chess.com-style article possible.
First real consumer. Probably the prep reader. Driving Priyome v0 from its actual needs avoids speculative design.
Naming for the project itself. Is Priyome the keeper-name or a codename? Russian chess term feels right thematically. Final call later.

Workspace placement

~/chess/
├── PROMOTE/             ← the stack (this project lives here)
│   ├── Tabia/
│   ├── Motif/
│   ├── Rabbit/
│   ├── Priyome/         ← this project
│   └── OpenFile/
├── TNMP/                ← reference implementation
├── reference-tree/      ← consumer app (will consume Priyome)
└── ...other apps

Independent git history per project (per workspace rules). Priyome consumes Tabia and Rabbit; doesn’t depend on Motif. Apps may consume both Motif and Priyome (a “chess app with embedded teaching content” wants components from both libraries).

What this document is NOT

Not a roadmap (no timelines or commitments)
Not a spec (no API definitions, no implementation plans)
Not exhaustive (the kickoff session will go far deeper)

It’s a hand-off — enough context to start the kickoff cold, plus the open questions worth pre-thinking before that session.