@ranx729/medieval-ornaments 0.1.0

package/ASSET-RIGHTS.md

@@ -0,0 +1,21 @@
+# Artwork provenance and rights
+
+The integration library has a scoped MIT license in LICENSE. That grant does
+not cover the ornament artwork. This collection has no established blanket
+artwork license. Availability in a public repository or npm package does not
+establish ownership or grant additional rights to the supplied references.
+
+| Family | Method and known source information |
+| --- | --- |
+| Five painted panels | AI-assisted transparent extractions from a user-supplied five-panel reference; original artist/source rights have not been established. Prompts and limitations are recorded in EXTRACTION-PROMPTS.json in the repository. |
+| Six floral styles | Editable geometric reconstructions inspired by a user-supplied six-style sheet. The watermarked sheet's pixels are not embedded or published as cleaned extractions. No blanket rights claim is made for the inspiration or exports. |
+| 38 numbered plate designs | Crops of a user-supplied ornament plate, narrow join adjustments, source-derived miter frames, and approximate color traces. Source scan rights/attribution have not been established. Original pixels, crop audit, and derivation records are retained in the repository. |
+
+The catalog identifies each design's derivation and reference family. PNG/WebP
+preserve the painted source appearance where documented; SVG traces can lose
+detail. Adapted corners are not recovered historical originals.
+
+Source sheets, extraction prompts, and detailed audit records remain at
+https://github.com/adrian729/medieval-ornaments . They are not part of the npm
+runtime package. The package includes this notice and the design catalog so
+integrators can retain the distinction between software and artwork rights.

package/LICENSE

@@ -0,0 +1,31 @@
+Licensing scope
+===============
+
+The MIT grant below applies to the integration library in lib/ (excluding the
+artwork metadata's underlying artwork), scripts/build-library.mjs,
+scripts/build-browser.mjs, package integration tests/examples, and
+docs/INTEGRATION.md, and the shared ornaments.css usage rules. It does not license the supplied reference artwork,
+extracted panels, reconstructed ornaments, traces, or exported SVG/PNG/WebP
+assets. See ASSET-RIGHTS.md for their separate status.
+
+MIT License
+
+Copyright (c) 2026 medieval-ornaments contributors
+
+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,183 @@
+# Medieval ornaments
+
+Reusable painted decorations and editable border designs, with PNG, lossless WebP, and smaller raster sizes. This repository is separate from [medieval-cutouts](https://github.com/adrian729/medieval-cutouts).
+
+## Install and integrate
+
+```sh
+npm install @ranx729/medieval-ornaments
+```
+
+Dependency-free vanilla JavaScript, optional React components, TypeScript declarations, and categorized discovery use the same normalized contract. See the [integration guide](https://github.com/adrian729/medieval-ornaments/blob/main/docs/INTEGRATION.md), [plain JS example](https://adrian729.github.io/medieval-ornaments/examples/vanilla/), [React example](https://adrian729.github.io/medieval-ornaments/examples/react/), and [browser ZIP](https://adrian729.github.io/medieval-ornaments/medieval-ornaments-browser.zip).
+
+```js
+import { createDivider } from '@ranx729/medieval-ornaments';
+import '@ranx729/medieval-ornaments/styles.css';
+
+const divider = createDivider(element, {
+  design: 'plate-02-stepped-ribbon', orientation: 'horizontal', length: '100%'
+});
+// divider.update({ orientation: 'vertical' });
+// divider.destroy();
+```
+
+```jsx
+import { OrnamentDivider, OrnamentFrame, OrnamentImage } from '@ranx729/medieval-ornaments/react';
+import '@ranx729/medieval-ornaments/styles.css';
+
+<OrnamentDivider design="plate-02-stepped-ribbon" />
+<OrnamentDivider design="plate-02-stepped-ribbon" orientation="horizontal" />
+<OrnamentFrame design="red-berry-vine" size={33}><YourContent /></OrnamentFrame>
+<OrnamentImage design="floral-bird-panel-blue" size={128} />
+```
+
+Only `design` is required. Dividers default to the chosen artwork's original direction; horizontal/vertical automatically choose matching assets. Geometry, formats, and smaller raster sizes come from the catalog. Import `findOrnaments({ use: 'frame', categories: ['floral'] })` to discover compatible designs. Frames/dividers support the 40 repeat designs; images support the nine whole decorations.
+
+Images default to version-pinned CDN URLs and load only when selected. To self-host:
+
+```sh
+npx medieval-ornaments copy-assets public/ornaments --design red-berry-vine
+```
+
+Pass `assetsBase: '/ornaments/'` in vanilla or `assetsBase="/ornaments/"` in React. No artwork build or Python is needed by consumers. The integration code has a scoped [MIT license](LICENSE); artwork retains its separately documented [rights status](ASSET-RIGHTS.md).
+
+## Artwork collection
+
+- **6 floral border styles:** editable vectors inspired by the supplied sheet, with complete motifs and matching corners.
+- **38 numbered plate designs:** original painted pixels cut into audited units, plus editable color traces and untouched reference crops. Alternating motifs/colors and native proportions are retained. Plate 11, 16, 36, and 37 are whole decorations because the supplied regions do not establish a usable repeating strip.
+- **5 painted vertical ornaments:** transparent AI-assisted extractions; complete decorations rather than seamless tiles.
+
+The 40 repeating styles include matching corners and a frame atlas. Painted plate frames use source pixels with reflected miter corners; their SVG alternatives are color traces, not exact historical reproductions. The original sheet, crop choices, repeat rationale, and traces are preserved in the repository.
+
+## Preview and use
+
+Open the [small usage demo](https://adrian729.github.io/medieval-ornaments/) for a decorated card, repeating divider, and painted flourish, with copyable HTML/CSS. It includes a dark background, frame choices, and border thickness controls. The [design browser](https://adrian729.github.io/medieval-ornaments/examples/) groups designs by use: frames, repeating dividers, or whole painted decorations. Filter by category, search subjects or colors, and choose a visual preview card. Preview controls apply to the selected use.
+
+Use [ornaments.css](ornaments.css) for consistent classes: `ornament-frame`, `ornament-divider`, and `ornament-image`. Set `--ornament-image` and `--ornament-size`; the stylesheet handles the shared geometry. [Usage details and exceptions](USAGE.md#shared-usage-contract) explain the optional settings.
+
+Run `python3 -m http.server 8765` in this folder and open [the interactive preview](http://localhost:8765/examples/). Frames offer width, height, and thickness; dividers offer orientation, available length, and thickness; painted decorations offer image height. Divider sections remain complete and centered within the available length. Switch between available formats and inspect the original reference where available. Every repeat tile includes a rotated version for using it in either direction with the shared CSS.
+
+The [artwork review page](https://adrian729.github.io/medieval-ornaments/examples/review.html) compares originals, extracted units, repeated strips, and frames at 33px. Switch between painted raster artwork and SVG traces.
+
+The demo is also at `examples/demo.html`; serve the local checkout as described above so it can load the catalog.
+
+```html
+<img src="https://raw.githubusercontent.com/adrian729/medieval-ornaments/main/webp/256/floral-bird-panel-blue.webp"
+     alt="" height="256">
+```
+
+For a scalable frame:
+
+```css
+.ornament-frame {
+  --ornament-image: url("https://adrian729.github.io/medieval-ornaments/svg/red-berry-vine-border.svg");
+  --ornament-size: 32px;
+}
+```
+
+Include `ornaments.css` once and add `class="ornament-frame"` to your element.
+
+Frames fit whole repeat units with `round`, so the edges end at the phase expected by their corners. Partial periods can cut motifs and are not an offered frame option. Use the supplied atlas rather than rotating source-derived corners yourself. See [usage details](USAGE.md) and [selection guidance for LLMs](SELECTION.md).
+
+## Formats and sizes
+
+`images.json` is the machine-readable catalog. `png/` and `webp/` contain masters; subfolders `128/`, `256/`, `512/`, and `768/` contain variants whose longest dimension is at most that size. A variant exists only when smaller than its master. Every size is made directly from the master; original raster artwork is never enlarged. SVGs are resolution-independent. Floral vector raster masters are at most 1024px. Numbered plate raster tiles, corners, and frames retain native source pixels. Atlas exports use integer slice boundaries; a size is omitted when it cannot meet that constraint without enlargement. Read actual dimensions from the catalog.
+
+Painted ornament PNGs retain transparent backgrounds and are capped at the supplied image's 650px height. Exact reference crops retain their original paper/background; the two L-shaped corner crops mask neighboring designs. PNG and WebP pairs have identical dimensions, alpha, and visible pixels.
+
+## Maintain the collection
+
+Read [AGENTS.md](AGENTS.md) before editing. Install and regenerate:
+
+```sh
+python3 -m venv --system-site-packages .venv
+.venv/bin/python -m pip install -r requirements.txt
+.venv/bin/python scripts/build_assets.py
+.venv/bin/python scripts/catalog.py
+.venv/bin/python scripts/catalog.py --check
+```
+
+The five extraction prompts and method are recorded in [EXTRACTION-PROMPTS.json](EXTRACTION-PROMPTS.json). Reference crop coordinates are in [reference-crops.json](reference-crops.json). Repeat/whole decisions and join adjustments are recorded in [source-patterns.json](source-patterns.json). Optional retracing uses Python 3.12 with `requirements-trace.txt`; normal builds use the checked-in traces. Asset metadata records whether artwork is an extraction, reconstruction, source crop/color trace, or reference crop. This repository does not establish ownership or a blanket license for the supplied reference artwork; no source attribution has been invented. The ornament vector code and exported artwork assets are provided without a blanket license until provenance is established. The npm integration software's grant is scoped separately in [LICENSE](LICENSE).
+
+## Develop and release the library
+
+```sh
+npm ci
+npm run build
+npm test
+npm run test:types
+npm run test:integration
+npm run build:browser
+npm pack
+```
+
+The library build generates metadata/types from `images.json` without changing artwork. Consumer checks install a real archive and exercise native/bundled vanilla, React 18/19, production/development, SSR/hydration, types, and self-hosting. Chromium is required for browser checks. The Pages workflow builds the React example and browser download. Follow [the integration guide's release steps](docs/INTEGRATION.md#examples-and-development) and record results in [QA.md](QA.md).
+
+[Quality checks](QA.md) cover every exported file and all formats in the browser preview.
+
+<!-- gallery:start -->
+## Browse designs
+
+| Category | Designs |
+| --- | --- |
+| `animals` | 4 |
+| `botanical` | 23 |
+| `floral` | 19 |
+| `geometric` | 20 |
+| `knotwork` | 2 |
+| `ribbons` | 2 |
+| `scrollwork` | 23 |
+
+| Preview | Design | Type | Files |
+| --- | --- | --- | --- |
+| <img src="webp/128/butterfly-panel-red.webp" height="72" alt="butterfly-panel-red"> | `butterfly-panel-red` | standalone | [PNG](png/butterfly-panel-red.png) · [WebP](webp/butterfly-panel-red.webp) |
+| <img src="webp/128/floral-bird-panel-blue.webp" height="72" alt="floral-bird-panel-blue"> | `floral-bird-panel-blue` | standalone | [PNG](png/floral-bird-panel-blue.png) · [WebP](webp/floral-bird-panel-blue.webp) |
+| <img src="webp/128/floral-bird-panel-left.webp" height="72" alt="floral-bird-panel-left"> | `floral-bird-panel-left` | standalone | [PNG](png/floral-bird-panel-left.png) · [WebP](webp/floral-bird-panel-left.webp) |
+| <img src="webp/128/floral-bird-panel-right.webp" height="72" alt="floral-bird-panel-right"> | `floral-bird-panel-right` | standalone | [PNG](png/floral-bird-panel-right.png) · [WebP](webp/floral-bird-panel-right.webp) |
+| <img src="webp/128/gold-leaf-scroll.webp" height="72" alt="gold-leaf-scroll"> | `gold-leaf-scroll` | repeat-tile | [PNG](png/gold-leaf-scroll.png) · [WebP](webp/gold-leaf-scroll.webp) · [SVG](svg/gold-leaf-scroll.svg) · [Rotated tile](svg/gold-leaf-scroll-rotated.svg) · [Corner](svg/gold-leaf-scroll-corner.svg) · [Border atlas](svg/gold-leaf-scroll-border.svg) |
+| <img src="webp/128/gold-quatrefoil-vine.webp" height="72" alt="gold-quatrefoil-vine"> | `gold-quatrefoil-vine` | repeat-tile | [PNG](png/gold-quatrefoil-vine.png) · [WebP](webp/gold-quatrefoil-vine.webp) · [SVG](svg/gold-quatrefoil-vine.svg) · [Rotated tile](svg/gold-quatrefoil-vine-rotated.svg) · [Corner](svg/gold-quatrefoil-vine-corner.svg) · [Border atlas](svg/gold-quatrefoil-vine-border.svg) |
+| <img src="webp/128/interlocking-ribbon.webp" height="72" alt="interlocking-ribbon"> | `interlocking-ribbon` | repeat-tile | [PNG](png/interlocking-ribbon.png) · [WebP](webp/interlocking-ribbon.webp) · [SVG](svg/interlocking-ribbon.svg) · [Rotated tile](svg/interlocking-ribbon-rotated.svg) · [Corner](svg/interlocking-ribbon-corner.svg) · [Border atlas](svg/interlocking-ribbon-border.svg) |
+| <img src="webp/plate-01-linked-scrolls.webp" height="72" alt="plate-01-linked-scrolls"> | `plate-01-linked-scrolls` | repeat-tile | [PNG](png/plate-01-linked-scrolls.png) · [WebP](webp/plate-01-linked-scrolls.webp) · [SVG](svg/plate-01-linked-scrolls.svg) · [Rotated tile](svg/plate-01-linked-scrolls-rotated.svg) · [Corner](svg/plate-01-linked-scrolls-corner.svg) · [Border atlas](svg/plate-01-linked-scrolls-border.svg) · [Reference crop](png/plate-01-linked-scrolls-reference.png) |
+| <img src="webp/plate-02-stepped-ribbon.webp" height="72" alt="plate-02-stepped-ribbon"> | `plate-02-stepped-ribbon` | repeat-tile | [PNG](png/plate-02-stepped-ribbon.png) · [WebP](webp/plate-02-stepped-ribbon.webp) · [SVG](svg/plate-02-stepped-ribbon.svg) · [Rotated tile](svg/plate-02-stepped-ribbon-rotated.svg) · [Corner](svg/plate-02-stepped-ribbon-corner.svg) · [Border atlas](svg/plate-02-stepped-ribbon-border.svg) · [Reference crop](png/plate-02-stepped-ribbon-reference.png) |
+| <img src="webp/plate-03-spiral-bands.webp" height="72" alt="plate-03-spiral-bands"> | `plate-03-spiral-bands` | repeat-tile | [PNG](png/plate-03-spiral-bands.png) · [WebP](webp/plate-03-spiral-bands.webp) · [SVG](svg/plate-03-spiral-bands.svg) · [Rotated tile](svg/plate-03-spiral-bands-rotated.svg) · [Corner](svg/plate-03-spiral-bands-corner.svg) · [Border atlas](svg/plate-03-spiral-bands-border.svg) · [Reference crop](png/plate-03-spiral-bands-reference.png) |
+| <img src="webp/plate-04-heart-and-diamond.webp" height="72" alt="plate-04-heart-and-diamond"> | `plate-04-heart-and-diamond` | repeat-tile | [PNG](png/plate-04-heart-and-diamond.png) · [WebP](webp/plate-04-heart-and-diamond.webp) · [SVG](svg/plate-04-heart-and-diamond.svg) · [Rotated tile](svg/plate-04-heart-and-diamond-rotated.svg) · [Corner](svg/plate-04-heart-and-diamond-corner.svg) · [Border atlas](svg/plate-04-heart-and-diamond-border.svg) · [Reference crop](png/plate-04-heart-and-diamond-reference.png) |
+| <img src="webp/plate-05-blue-curls.webp" height="72" alt="plate-05-blue-curls"> | `plate-05-blue-curls` | repeat-tile | [PNG](png/plate-05-blue-curls.png) · [WebP](webp/plate-05-blue-curls.webp) · [SVG](svg/plate-05-blue-curls.svg) · [Rotated tile](svg/plate-05-blue-curls-rotated.svg) · [Corner](svg/plate-05-blue-curls-corner.svg) · [Border atlas](svg/plate-05-blue-curls-border.svg) · [Reference crop](png/plate-05-blue-curls-reference.png) |
+| <img src="webp/128/plate-06-paired-red-scrolls.webp" height="72" alt="plate-06-paired-red-scrolls"> | `plate-06-paired-red-scrolls` | repeat-tile | [PNG](png/plate-06-paired-red-scrolls.png) · [WebP](webp/plate-06-paired-red-scrolls.webp) · [SVG](svg/plate-06-paired-red-scrolls.svg) · [Rotated tile](svg/plate-06-paired-red-scrolls-rotated.svg) · [Corner](svg/plate-06-paired-red-scrolls-corner.svg) · [Border atlas](svg/plate-06-paired-red-scrolls-border.svg) · [Reference crop](png/plate-06-paired-red-scrolls-reference.png) |
+| <img src="webp/plate-07-blue-heart-leaves.webp" height="72" alt="plate-07-blue-heart-leaves"> | `plate-07-blue-heart-leaves` | repeat-tile | [PNG](png/plate-07-blue-heart-leaves.png) · [WebP](webp/plate-07-blue-heart-leaves.webp) · [SVG](svg/plate-07-blue-heart-leaves.svg) · [Rotated tile](svg/plate-07-blue-heart-leaves-rotated.svg) · [Corner](svg/plate-07-blue-heart-leaves-corner.svg) · [Border atlas](svg/plate-07-blue-heart-leaves-border.svg) · [Reference crop](png/plate-07-blue-heart-leaves-reference.png) |
+| <img src="webp/plate-08-diagonal-cross.webp" height="72" alt="plate-08-diagonal-cross"> | `plate-08-diagonal-cross` | repeat-tile | [PNG](png/plate-08-diagonal-cross.png) · [WebP](webp/plate-08-diagonal-cross.webp) · [SVG](svg/plate-08-diagonal-cross.svg) · [Rotated tile](svg/plate-08-diagonal-cross-rotated.svg) · [Corner](svg/plate-08-diagonal-cross-corner.svg) · [Border atlas](svg/plate-08-diagonal-cross-border.svg) · [Reference crop](png/plate-08-diagonal-cross-reference.png) |
+| <img src="webp/plate-09-interlaced-knot.webp" height="72" alt="plate-09-interlaced-knot"> | `plate-09-interlaced-knot` | repeat-tile | [PNG](png/plate-09-interlaced-knot.png) · [WebP](webp/plate-09-interlaced-knot.webp) · [SVG](svg/plate-09-interlaced-knot.svg) · [Rotated tile](svg/plate-09-interlaced-knot-rotated.svg) · [Corner](svg/plate-09-interlaced-knot-corner.svg) · [Border atlas](svg/plate-09-interlaced-knot-border.svg) · [Reference crop](png/plate-09-interlaced-knot-reference.png) |
+| <img src="webp/128/plate-10-blue-palmettes.webp" height="72" alt="plate-10-blue-palmettes"> | `plate-10-blue-palmettes` | repeat-tile | [PNG](png/plate-10-blue-palmettes.png) · [WebP](webp/plate-10-blue-palmettes.webp) · [SVG](svg/plate-10-blue-palmettes.svg) · [Rotated tile](svg/plate-10-blue-palmettes-rotated.svg) · [Corner](svg/plate-10-blue-palmettes-corner.svg) · [Border atlas](svg/plate-10-blue-palmettes-border.svg) · [Reference crop](png/plate-10-blue-palmettes-reference.png) |
+| <img src="webp/128/plate-11-acanthus-scroll.webp" height="72" alt="plate-11-acanthus-scroll"> | `plate-11-acanthus-scroll` | standalone | [PNG](png/plate-11-acanthus-scroll.png) · [WebP](webp/plate-11-acanthus-scroll.webp) · [SVG](svg/plate-11-acanthus-scroll.svg) · [Reference crop](png/plate-11-acanthus-scroll-reference.png) |
+| <img src="webp/plate-12-arched-diamonds.webp" height="72" alt="plate-12-arched-diamonds"> | `plate-12-arched-diamonds` | repeat-tile | [PNG](png/plate-12-arched-diamonds.png) · [WebP](webp/plate-12-arched-diamonds.webp) · [SVG](svg/plate-12-arched-diamonds.svg) · [Rotated tile](svg/plate-12-arched-diamonds-rotated.svg) · [Corner](svg/plate-12-arched-diamonds-corner.svg) · [Border atlas](svg/plate-12-arched-diamonds-border.svg) · [Reference crop](png/plate-12-arched-diamonds-reference.png) |
+| <img src="webp/128/plate-13-leaf-and-flower-vine.webp" height="72" alt="plate-13-leaf-and-flower-vine"> | `plate-13-leaf-and-flower-vine` | repeat-tile | [PNG](png/plate-13-leaf-and-flower-vine.png) · [WebP](webp/plate-13-leaf-and-flower-vine.webp) · [SVG](svg/plate-13-leaf-and-flower-vine.svg) · [Rotated tile](svg/plate-13-leaf-and-flower-vine-rotated.svg) · [Corner](svg/plate-13-leaf-and-flower-vine-corner.svg) · [Border atlas](svg/plate-13-leaf-and-flower-vine-border.svg) · [Reference crop](png/plate-13-leaf-and-flower-vine-reference.png) |
+| <img src="webp/plate-14-crossed-diamonds.webp" height="72" alt="plate-14-crossed-diamonds"> | `plate-14-crossed-diamonds` | repeat-tile | [PNG](png/plate-14-crossed-diamonds.png) · [WebP](webp/plate-14-crossed-diamonds.webp) · [SVG](svg/plate-14-crossed-diamonds.svg) · [Rotated tile](svg/plate-14-crossed-diamonds-rotated.svg) · [Corner](svg/plate-14-crossed-diamonds-corner.svg) · [Border atlas](svg/plate-14-crossed-diamonds-border.svg) · [Reference crop](png/plate-14-crossed-diamonds-reference.png) |
+| <img src="webp/plate-15-diamond-square.webp" height="72" alt="plate-15-diamond-square"> | `plate-15-diamond-square` | repeat-tile | [PNG](png/plate-15-diamond-square.png) · [WebP](webp/plate-15-diamond-square.webp) · [SVG](svg/plate-15-diamond-square.svg) · [Rotated tile](svg/plate-15-diamond-square-rotated.svg) · [Corner](svg/plate-15-diamond-square-corner.svg) · [Border atlas](svg/plate-15-diamond-square-border.svg) · [Reference crop](png/plate-15-diamond-square-reference.png) |
+| <img src="webp/plate-16-stepped-corner.webp" height="72" alt="plate-16-stepped-corner"> | `plate-16-stepped-corner` | standalone | [PNG](png/plate-16-stepped-corner.png) · [WebP](webp/plate-16-stepped-corner.webp) · [SVG](svg/plate-16-stepped-corner.svg) · [Reference crop](png/plate-16-stepped-corner-reference.png) |
+| <img src="webp/plate-17-stepped-arches.webp" height="72" alt="plate-17-stepped-arches"> | `plate-17-stepped-arches` | repeat-tile | [PNG](png/plate-17-stepped-arches.png) · [WebP](webp/plate-17-stepped-arches.webp) · [SVG](svg/plate-17-stepped-arches.svg) · [Rotated tile](svg/plate-17-stepped-arches-rotated.svg) · [Corner](svg/plate-17-stepped-arches-corner.svg) · [Border atlas](svg/plate-17-stepped-arches-border.svg) · [Reference crop](png/plate-17-stepped-arches-reference.png) |
+| <img src="webp/plate-18-fan-palmettes.webp" height="72" alt="plate-18-fan-palmettes"> | `plate-18-fan-palmettes` | repeat-tile | [PNG](png/plate-18-fan-palmettes.png) · [WebP](webp/plate-18-fan-palmettes.webp) · [SVG](svg/plate-18-fan-palmettes.svg) · [Rotated tile](svg/plate-18-fan-palmettes-rotated.svg) · [Corner](svg/plate-18-fan-palmettes-corner.svg) · [Border atlas](svg/plate-18-fan-palmettes-border.svg) · [Reference crop](png/plate-18-fan-palmettes-reference.png) |
+| <img src="webp/plate-19-cream-scrolls.webp" height="72" alt="plate-19-cream-scrolls"> | `plate-19-cream-scrolls` | repeat-tile | [PNG](png/plate-19-cream-scrolls.png) · [WebP](webp/plate-19-cream-scrolls.webp) · [SVG](svg/plate-19-cream-scrolls.svg) · [Rotated tile](svg/plate-19-cream-scrolls-rotated.svg) · [Corner](svg/plate-19-cream-scrolls-corner.svg) · [Border atlas](svg/plate-19-cream-scrolls-border.svg) · [Reference crop](png/plate-19-cream-scrolls-reference.png) |
+| <img src="webp/plate-20-segmented-medallions.webp" height="72" alt="plate-20-segmented-medallions"> | `plate-20-segmented-medallions` | repeat-tile | [PNG](png/plate-20-segmented-medallions.png) · [WebP](webp/plate-20-segmented-medallions.webp) · [SVG](svg/plate-20-segmented-medallions.svg) · [Rotated tile](svg/plate-20-segmented-medallions-rotated.svg) · [Corner](svg/plate-20-segmented-medallions-corner.svg) · [Border atlas](svg/plate-20-segmented-medallions-border.svg) · [Reference crop](png/plate-20-segmented-medallions-reference.png) |
+| <img src="webp/plate-21-green-flower-medallions.webp" height="72" alt="plate-21-green-flower-medallions"> | `plate-21-green-flower-medallions` | repeat-tile | [PNG](png/plate-21-green-flower-medallions.png) · [WebP](webp/plate-21-green-flower-medallions.webp) · [SVG](svg/plate-21-green-flower-medallions.svg) · [Rotated tile](svg/plate-21-green-flower-medallions-rotated.svg) · [Corner](svg/plate-21-green-flower-medallions-corner.svg) · [Border atlas](svg/plate-21-green-flower-medallions-border.svg) · [Reference crop](png/plate-21-green-flower-medallions-reference.png) |
+| <img src="webp/plate-22-white-petal-grid.webp" height="72" alt="plate-22-white-petal-grid"> | `plate-22-white-petal-grid` | repeat-tile | [PNG](png/plate-22-white-petal-grid.png) · [WebP](webp/plate-22-white-petal-grid.webp) · [SVG](svg/plate-22-white-petal-grid.svg) · [Rotated tile](svg/plate-22-white-petal-grid-rotated.svg) · [Corner](svg/plate-22-white-petal-grid-corner.svg) · [Border atlas](svg/plate-22-white-petal-grid-border.svg) · [Reference crop](png/plate-22-white-petal-grid-reference.png) |
+| <img src="webp/plate-23-crossed-ribbon-knots.webp" height="72" alt="plate-23-crossed-ribbon-knots"> | `plate-23-crossed-ribbon-knots` | repeat-tile | [PNG](png/plate-23-crossed-ribbon-knots.png) · [WebP](webp/plate-23-crossed-ribbon-knots.webp) · [SVG](svg/plate-23-crossed-ribbon-knots.svg) · [Rotated tile](svg/plate-23-crossed-ribbon-knots-rotated.svg) · [Corner](svg/plate-23-crossed-ribbon-knots-corner.svg) · [Border atlas](svg/plate-23-crossed-ribbon-knots-border.svg) · [Reference crop](png/plate-23-crossed-ribbon-knots-reference.png) |
+| <img src="webp/plate-24-gold-ring-scrolls.webp" height="72" alt="plate-24-gold-ring-scrolls"> | `plate-24-gold-ring-scrolls` | repeat-tile | [PNG](png/plate-24-gold-ring-scrolls.png) · [WebP](webp/plate-24-gold-ring-scrolls.webp) · [SVG](svg/plate-24-gold-ring-scrolls.svg) · [Rotated tile](svg/plate-24-gold-ring-scrolls-rotated.svg) · [Corner](svg/plate-24-gold-ring-scrolls-corner.svg) · [Border atlas](svg/plate-24-gold-ring-scrolls-border.svg) · [Reference crop](png/plate-24-gold-ring-scrolls-reference.png) |
+| <img src="webp/plate-25-greek-crosses.webp" height="72" alt="plate-25-greek-crosses"> | `plate-25-greek-crosses` | repeat-tile | [PNG](png/plate-25-greek-crosses.png) · [WebP](webp/plate-25-greek-crosses.webp) · [SVG](svg/plate-25-greek-crosses.svg) · [Rotated tile](svg/plate-25-greek-crosses-rotated.svg) · [Corner](svg/plate-25-greek-crosses-corner.svg) · [Border atlas](svg/plate-25-greek-crosses-border.svg) · [Reference crop](png/plate-25-greek-crosses-reference.png) |
+| <img src="webp/plate-26-eight-petal-rosette.webp" height="72" alt="plate-26-eight-petal-rosette"> | `plate-26-eight-petal-rosette` | repeat-tile | [PNG](png/plate-26-eight-petal-rosette.png) · [WebP](webp/plate-26-eight-petal-rosette.webp) · [SVG](svg/plate-26-eight-petal-rosette.svg) · [Rotated tile](svg/plate-26-eight-petal-rosette-rotated.svg) · [Corner](svg/plate-26-eight-petal-rosette-corner.svg) · [Border atlas](svg/plate-26-eight-petal-rosette-border.svg) · [Reference crop](png/plate-26-eight-petal-rosette-reference.png) |
+| <img src="webp/plate-27-blue-flower-medallions.webp" height="72" alt="plate-27-blue-flower-medallions"> | `plate-27-blue-flower-medallions` | repeat-tile | [PNG](png/plate-27-blue-flower-medallions.png) · [WebP](webp/plate-27-blue-flower-medallions.webp) · [SVG](svg/plate-27-blue-flower-medallions.svg) · [Rotated tile](svg/plate-27-blue-flower-medallions-rotated.svg) · [Corner](svg/plate-27-blue-flower-medallions-corner.svg) · [Border atlas](svg/plate-27-blue-flower-medallions-border.svg) · [Reference crop](png/plate-27-blue-flower-medallions-reference.png) |
+| <img src="webp/plate-28-angular-blue-meander.webp" height="72" alt="plate-28-angular-blue-meander"> | `plate-28-angular-blue-meander` | repeat-tile | [PNG](png/plate-28-angular-blue-meander.png) · [WebP](webp/plate-28-angular-blue-meander.webp) · [SVG](svg/plate-28-angular-blue-meander.svg) · [Rotated tile](svg/plate-28-angular-blue-meander-rotated.svg) · [Corner](svg/plate-28-angular-blue-meander-corner.svg) · [Border atlas](svg/plate-28-angular-blue-meander-border.svg) · [Reference crop](png/plate-28-angular-blue-meander-reference.png) |
+| <img src="webp/128/plate-29-red-acanthus.webp" height="72" alt="plate-29-red-acanthus"> | `plate-29-red-acanthus` | repeat-tile | [PNG](png/plate-29-red-acanthus.png) · [WebP](webp/plate-29-red-acanthus.webp) · [SVG](svg/plate-29-red-acanthus.svg) · [Rotated tile](svg/plate-29-red-acanthus-rotated.svg) · [Corner](svg/plate-29-red-acanthus-corner.svg) · [Border atlas](svg/plate-29-red-acanthus-border.svg) · [Reference crop](png/plate-29-red-acanthus-reference.png) |
+| <img src="webp/128/plate-30-layered-palmettes.webp" height="72" alt="plate-30-layered-palmettes"> | `plate-30-layered-palmettes` | repeat-tile | [PNG](png/plate-30-layered-palmettes.png) · [WebP](webp/plate-30-layered-palmettes.webp) · [SVG](svg/plate-30-layered-palmettes.svg) · [Rotated tile](svg/plate-30-layered-palmettes-rotated.svg) · [Corner](svg/plate-30-layered-palmettes-corner.svg) · [Border atlas](svg/plate-30-layered-palmettes-border.svg) · [Reference crop](png/plate-30-layered-palmettes-reference.png) |
+| <img src="webp/128/plate-31-alternating-florets.webp" height="72" alt="plate-31-alternating-florets"> | `plate-31-alternating-florets` | repeat-tile | [PNG](png/plate-31-alternating-florets.png) · [WebP](webp/plate-31-alternating-florets.webp) · [SVG](svg/plate-31-alternating-florets.svg) · [Rotated tile](svg/plate-31-alternating-florets-rotated.svg) · [Corner](svg/plate-31-alternating-florets-corner.svg) · [Border atlas](svg/plate-31-alternating-florets-border.svg) · [Reference crop](png/plate-31-alternating-florets-reference.png) |
+| <img src="webp/plate-32-linked-ovals.webp" height="72" alt="plate-32-linked-ovals"> | `plate-32-linked-ovals` | repeat-tile | [PNG](png/plate-32-linked-ovals.png) · [WebP](webp/plate-32-linked-ovals.webp) · [SVG](svg/plate-32-linked-ovals.svg) · [Rotated tile](svg/plate-32-linked-ovals-rotated.svg) · [Corner](svg/plate-32-linked-ovals-corner.svg) · [Border atlas](svg/plate-32-linked-ovals-border.svg) · [Reference crop](png/plate-32-linked-ovals-reference.png) |
+| <img src="webp/plate-33-leaf-scrolls.webp" height="72" alt="plate-33-leaf-scrolls"> | `plate-33-leaf-scrolls` | repeat-tile | [PNG](png/plate-33-leaf-scrolls.png) · [WebP](webp/plate-33-leaf-scrolls.webp) · [SVG](svg/plate-33-leaf-scrolls.svg) · [Rotated tile](svg/plate-33-leaf-scrolls-rotated.svg) · [Corner](svg/plate-33-leaf-scrolls-corner.svg) · [Border atlas](svg/plate-33-leaf-scrolls-border.svg) · [Reference crop](png/plate-33-leaf-scrolls-reference.png) |
+| <img src="webp/plate-34-nested-fans.webp" height="72" alt="plate-34-nested-fans"> | `plate-34-nested-fans` | repeat-tile | [PNG](png/plate-34-nested-fans.png) · [WebP](webp/plate-34-nested-fans.webp) · [SVG](svg/plate-34-nested-fans.svg) · [Rotated tile](svg/plate-34-nested-fans-rotated.svg) · [Corner](svg/plate-34-nested-fans-corner.svg) · [Border atlas](svg/plate-34-nested-fans-border.svg) · [Reference crop](png/plate-34-nested-fans-reference.png) |
+| <img src="webp/plate-35-crossed-white-stems.webp" height="72" alt="plate-35-crossed-white-stems"> | `plate-35-crossed-white-stems` | repeat-tile | [PNG](png/plate-35-crossed-white-stems.png) · [WebP](webp/plate-35-crossed-white-stems.webp) · [SVG](svg/plate-35-crossed-white-stems.svg) · [Rotated tile](svg/plate-35-crossed-white-stems-rotated.svg) · [Corner](svg/plate-35-crossed-white-stems-corner.svg) · [Border atlas](svg/plate-35-crossed-white-stems-border.svg) · [Reference crop](png/plate-35-crossed-white-stems-reference.png) |
+| <img src="webp/plate-36-greek-key.webp" height="72" alt="plate-36-greek-key"> | `plate-36-greek-key` | standalone | [PNG](png/plate-36-greek-key.png) · [WebP](webp/plate-36-greek-key.webp) · [SVG](svg/plate-36-greek-key.svg) · [Reference crop](png/plate-36-greek-key-reference.png) |
+| <img src="webp/plate-37-diamond-scroll.webp" height="72" alt="plate-37-diamond-scroll"> | `plate-37-diamond-scroll` | standalone | [PNG](png/plate-37-diamond-scroll.png) · [WebP](webp/plate-37-diamond-scroll.webp) · [SVG](svg/plate-37-diamond-scroll.svg) · [Reference crop](png/plate-37-diamond-scroll-reference.png) |
+| <img src="webp/plate-38-diagonal-meander.webp" height="72" alt="plate-38-diagonal-meander"> | `plate-38-diagonal-meander` | repeat-tile | [PNG](png/plate-38-diagonal-meander.png) · [WebP](webp/plate-38-diagonal-meander.webp) · [SVG](svg/plate-38-diagonal-meander.svg) · [Rotated tile](svg/plate-38-diagonal-meander-rotated.svg) · [Corner](svg/plate-38-diagonal-meander-corner.svg) · [Border atlas](svg/plate-38-diagonal-meander-border.svg) · [Reference crop](png/plate-38-diagonal-meander-reference.png) |
+| <img src="webp/128/red-berry-vine.webp" height="72" alt="red-berry-vine"> | `red-berry-vine` | repeat-tile | [PNG](png/red-berry-vine.png) · [WebP](webp/red-berry-vine.webp) · [SVG](svg/red-berry-vine.svg) · [Rotated tile](svg/red-berry-vine-rotated.svg) · [Corner](svg/red-berry-vine-corner.svg) · [Border atlas](svg/red-berry-vine-border.svg) |
+| <img src="webp/128/red-rosette-vine.webp" height="72" alt="red-rosette-vine"> | `red-rosette-vine` | repeat-tile | [PNG](png/red-rosette-vine.png) · [WebP](webp/red-rosette-vine.webp) · [SVG](svg/red-rosette-vine.svg) · [Rotated tile](svg/red-rosette-vine-rotated.svg) · [Corner](svg/red-rosette-vine-corner.svg) · [Border atlas](svg/red-rosette-vine-border.svg) |
+| <img src="webp/128/red-trefoil-vine.webp" height="72" alt="red-trefoil-vine"> | `red-trefoil-vine` | repeat-tile | [PNG](png/red-trefoil-vine.png) · [WebP](webp/red-trefoil-vine.webp) · [SVG](svg/red-trefoil-vine.svg) · [Rotated tile](svg/red-trefoil-vine-rotated.svg) · [Corner](svg/red-trefoil-vine-corner.svg) · [Border atlas](svg/red-trefoil-vine-border.svg) |
+| <img src="webp/128/spiral-ribbon-column.webp" height="72" alt="spiral-ribbon-column"> | `spiral-ribbon-column` | standalone | [PNG](png/spiral-ribbon-column.png) · [WebP](webp/spiral-ribbon-column.webp) |
+
+<!-- gallery:end -->

package/SELECTION.md

@@ -0,0 +1,22 @@
+# Selection guidance
+
+Use `images.json` as the source of truth. Selection fields are deliberately generic:
+
+The npm package generates `/catalog.json` and immutable `ornaments` from this catalog, adding `uses` (`frame`, `divider`, or `image`) and available `formats`. Use `findOrnaments({ use, categories, subjects, colors, query })` for alphabetical selection without a React dependency or image requests. Library divider orientation can be `original`, `horizontal`, or `vertical`; it selects the matching original/rotated asset automatically. See [the integration guide](docs/INTEGRATION.md).
+
+| Field | Meaning |
+| --- | --- |
+| `description` | Plain-language appearance, source family, and adaptation |
+| `categories` | Broad themes: floral, botanical, animals, geometric, knotwork, ribbons, scrollwork |
+| `subjects` | Depicted forms, such as bird, butterfly, leaf, flower, ribbon, or diamond |
+| `facing` | left, right, front, mixed, or unclear; unclear is normal for abstract ornaments |
+| `colors` | Main named colors present in the asset and its adapted corner |
+| `composition` | single-ornament, standalone, or repeat-tile |
+
+Also inspect `kind`, `repeat_axis`, and `derivation` before using an asset. Choose `standalone` for complete panels, compositions, or original corner artwork. Choose `repeat-tile` for an extendable strip or frame and take its matching components. A reference crop is for its original appearance and must not be assumed seamless. Floral reconstructions and source-derived miter corners are adaptations. Numbered raster assets retain painted source pixels; their SVGs are approximate color traces.
+
+Every repeat design offers both divider directions: the main tile follows its original `repeat_axis`, while `components.rotated_tile` provides the opposite axis. Choose the matching tile and set `data-axis="y"` for vertical dividers. Both use the same `repeat_ratio`; switching the CSS axis without switching the image would stretch the artwork.
+
+For raster files, choose a listed variant rather than guessing a filename. `max_dimension` is a size-folder upper bound, not necessarily the rendered longest dimension. Use actual `width` and `height` to estimate resolution at the intended display size and pixel density. Never invent a missing larger size. Use SVG when scalable traced geometry is appropriate; use numbered PNG/WebP for the original painted appearance. Read `repeat_ratio` and `border_image_slice_percent`; do not assume a fixed geometry or rotate source miter corners independently. Frames require whole-unit fitting (`round`).
+
+Prefer a restrained pattern for small corners or dense layouts. Use tall standalone panels beside content and repeat strips for separators. Check the preview at the intended size, especially for detailed ornament, mirrored designs, and dark backgrounds. Use an empty alt attribute for purely decorative images; describe meaningful imagery when it conveys content.

package/USAGE.md

@@ -0,0 +1,100 @@
+# Choosing and assembling ornaments
+
+For normalized vanilla JS and React components with automatic orientation, geometry, format, and size selection, use the npm package. See [docs/INTEGRATION.md](docs/INTEGRATION.md). The CSS contract below remains available for direct HTML/CSS use.
+
+## Shared usage contract
+
+Include [ornaments.css](ornaments.css) once:
+
+```html
+<link rel="stylesheet" href="https://adrian729.github.io/medieval-ornaments/ornaments.css">
+```
+
+| Class | Asset | Size means |
+| --- | --- | --- |
+| `ornament-divider` | Main or `components.rotated_tile` repeat tile | Strip thickness |
+| `ornament-frame` | `components.border_image` | Border thickness |
+| `ornament-image` | Whole decoration | Image height |
+
+Set `--ornament-image` to an absolute asset URL for frames/dividers, and `--ornament-size` to the display size. Relative URLs in this variable resolve against the shared stylesheet; local assets therefore use `url('svg/design.svg')` or `url('webp/design.webp')`. Resolve catalog paths in JavaScript with `new URL(path, collectionBaseUrl).href`.
+
+Use the catalog's `border_image_slice_percent` for `--ornament-slice`, and its `repeat_ratio` for `--ornament-ratio`. Plate designs retain their native proportions, so these values differ between designs. The six floral vectors retain the defaults of 256/96 and 21.42857142857143%.
+
+```html
+<article class="ornament-frame" style="
+  --ornament-image: url('https://adrian729.github.io/medieval-ornaments/svg/red-berry-vine-border.svg');
+  --ornament-slice: 21.42857142857143%;
+  --ornament-size: 33px; padding: 24px;">
+  Your content
+</article>
+```
+
+## Frames
+
+Frames always use `round`, fitting complete units into each side. A partial unit from `repeat` cannot meet the corner's expected phase and can cut petals or leaves. Whole-unit fitting can slightly adjust the length of a motif, so inspect narrow frames and thick borders.
+
+Use the complete supplied atlas. Floral corners are adapted turns. Painted plate corners are mitered reflections of the same pattern; the atlas has four correctly phased corners and reflected edge directions. The separate `components.corner` export is the top-left piece, not a universal piece to rotate blindly. Diagonal miter reflections are adaptations, not recovered historical corners.
+
+Slice with the catalog percentage, without `fill`. The center remains transparent. Set a real CSS border width through `--ornament-size`; no `border-radius` clipping is promised.
+
+The demo uses SVG for its floral frame and source WebP for its painted plate frames. The browser offers the corresponding SVG color traces for comparison.
+
+## Dividers
+
+Use the main tile as a repeating background. For a horizontal divider:
+
+```html
+<div class="ornament-divider" style="
+  --ornament-image: url('https://adrian729.github.io/medieval-ornaments/svg/red-berry-vine.svg');
+  --ornament-size: 24px; --ornament-ratio: 2.6666666666666665;
+  --ornament-length: 100%;" aria-hidden="true"></div>
+```
+
+Every repeat design also supplies `components.rotated_tile`: the same artwork turned 90 degrees, in SVG, PNG, WebP, and smaller sizes. Its `repeat_axis` is opposite to the main tile's, and its `repeat_ratio` is unchanged. Choose the asset whose axis matches the direction you want. PNG/WebP rotations rearrange existing pixels without interpolation or enlargement.
+
+Vertical dividers add `data-axis="y"`; the available length then sets height and the thickness sets width. Setting that attribute alone does not rotate a horizontal image: use the matching vertical asset too. For example:
+
+```html
+<div class="ornament-divider" data-axis="y" style="
+  --ornament-image: url('https://adrian729.github.io/medieval-ornaments/svg/red-berry-vine-rotated.svg');
+  --ornament-size: 24px; --ornament-ratio: 2.6666666666666665;
+  --ornament-length: 240px;" aria-hidden="true"></div>
+```
+
+The browser's Orientation selector offers Horizontal, Vertical, and Original direction; asset links follow your choice. `--ornament-length` sets the available space. The shared CSS fits as many complete, contiguous sections as possible and centers them within that space, leaving equal empty space at both ends. The artwork retains its thickness and proportions. If even one section is too long, nothing is painted: increase the available length or reduce the thickness.
+
+This works responsively with `--ornament-length:100%` and requires no JavaScript. The painted background lives on `::before`; leave that pseudo-element available. Whole-section fitting uses [CSS round()](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/round). Older browsers without that function fit complete tiles by slightly adjusting their length instead. Frames keep their separate `round` fitting around corners.
+
+## Whole decorations
+
+The five extracted panels and plate 11, 16, 36, and 37 have `kind=standalone` and `repeat_axis=none`. They have no frame atlas. Use `ornament-image` or a normal `<img>` and preserve proportions. The plate exceptions retain complete acanthus/corner artwork rather than pretending their supplied regions form seamless strips.
+
+```html
+<img class="ornament-image"
+     src="https://adrian729.github.io/medieval-ornaments/webp/256/floral-bird-panel-blue.webp"
+     style="--ornament-size: 256px" alt="">
+```
+
+Use empty alt text for purely decorative art; describe an image when its subject conveys meaning.
+
+## Source artwork and vectors
+
+The 38 reference crops reproduce the supplied pixels without enlargement; two L-shaped crops mask neighboring regions. The full original sheet is in `sources/`. [source-patterns.json](source-patterns.json) records crop bounds, direction, unit choice, whole-art exceptions, and repeat rationale.
+
+Numbered PNG/WebP tiles retain painted pixels. Their repeating units have a two-pixel adjustment at both ends to reconcile print/scanning differences; the interior is unchanged. Their native corners/atlases rearrange and reflect these pixels without interpolation or enlargement. Some entries deliberately repeat one complete square/medallion cell instead of claiming an unavailable full color cycle. These choices are explicit in the catalog.
+
+The numbered SVGs trace those actual shapes with an adaptive color palette. They approximate print tones and curves, and can lose subtle detail; choose PNG/WebP when the painted appearance matters. They contain real vector paths, not embedded raster images. The six floral designs are geometric redraws; the watermarked sheet's pixels are not embedded or published as cleaned artwork.
+
+The five transparent panels are AI-assisted extractions and can reinterpret detail. Their master dimensions are capped at the supplied source's 650px height.
+
+## Raster size selection
+
+Choose listed variants by actual width/height and the display size times pixel density; do not guess filenames. Every smaller export comes directly from its master. Source pixels are never exported enlarged.
+
+Size folders are upper bounds. Frame variants use dimensions that keep slice boundaries on integer pixels, so a `128/` atlas might be 126px and some smaller atlas sizes are absent. Native plate assets are already small. SVG can scale its traced shapes, but does not recover missing source detail.
+
+The [design browser](https://adrian729.github.io/medieval-ornaments/examples/) filters by use, category, subjects, and colors. The [artwork comparison page](https://adrian729.github.io/medieval-ornaments/examples/review.html) shows originals, units, repetitions, and frames, with format/background/thickness controls.
+
+## Technical references
+
+Frame fitting follows [CSS border-image-repeat](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/border-image-repeat); slice geometry follows [border-image-slice](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/border-image-slice). Source color tracing uses [VTracer](https://github.com/visioncortex/vtracer); ordinary SVG rendering uses [CairoSVG](https://cairosvg.org/documentation/).