@ranx729/medieval-ornaments 0.1.0

package/lib/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { mkdir, copyFile, realpath } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { ornaments } from './catalog.js';
+import { findOrnaments, getOrnament } from './resolve.js';
+
+const root = fileURLToPath(new URL('../', import.meta.url));
+const help = `Usage: medieval-ornaments copy-assets <destination> [--design <name>]... [--format svg|png|webp|all]
+
+Copies the selected designs and their components/variants, the shared CSS, a
+filtered catalog.json, and rights notices. Without --design, copies all designs.
+Pass the destination's public URL as assetsBase in your application.
+Example: medieval-ornaments copy-assets public/ornaments --design red-berry-vine
+`;
+
+export async function main(args) {
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) { console.log(help); return; }
+  if (args[0] !== 'copy-assets' || !args[1] || args[1].startsWith('--')) throw new Error(help);
+  const names = [], formats = ['svg', 'png', 'webp'];
+  let format = 'all';
+  for (let i = 2; i < args.length; i++) {
+    const flag = args[i], value = args[++i];
+    if (!value) throw new Error(`Missing value for ${flag}.`);
+    if (flag === '--design') names.push(getOrnament(value).name);
+    else if (flag === '--format' && [...formats, 'all'].includes(value)) format = value;
+    else throw new Error(`Invalid argument: ${flag} ${value}.\n${help}`);
+  }
+  const items = names.length ? findOrnaments().filter(item => names.includes(item.name)) : ornaments;
+  if (format !== 'all' && items.some(item => !item.formats.includes(format))) throw new Error(`Some selected designs do not support ${format}. Select compatible designs with --design or use --format all.`);
+  const destination = path.resolve(args[1]);
+  await mkdir(destination, { recursive: true });
+  const resolved = await realpath(destination);
+  // Never overwrite the installed package, its source, or an ancestor of either.
+  const packageRoot = await realpath(root);
+  if (resolved === packageRoot || packageRoot.startsWith(resolved + path.sep) || resolved.startsWith(packageRoot + path.sep)) throw new Error('Choose a destination outside the package directory.');
+  const paths = new Set(['ornaments.css', 'LICENSE', 'ASSET-RIGHTS.md']);
+  for (const item of items) for (const component of [item, ...Object.values(item.components)]) {
+    for (const asset of [component, ...component.variants]) {
+      for (const type of formats) if ((format === 'all' || format === type) && asset[type]) paths.add(asset[type]);
+    }
+  }
+  for (const relative of paths) {
+    const target = path.join(destination, relative);
+    await mkdir(path.dirname(target), { recursive: true });
+    // Resolve existing targets too: an accidental symlink must not redirect writes.
+    const parent = await realpath(path.dirname(target));
+    if (parent !== resolved && !parent.startsWith(resolved + path.sep)) throw new Error('Destination contains a symlink outside its root.');
+    try {
+      const existing = await realpath(target);
+      if (!existing.startsWith(resolved + path.sep)) throw new Error('Destination file points outside its root.');
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    await copyFile(path.join(root, relative), target);
+  }
+  // Write a filtered catalog; omit unavailable formats when only one was copied.
+  const catalog = JSON.parse(JSON.stringify(items));
+  if (format !== 'all') for (const item of catalog) {
+    item.formats = item.formats.filter(type => type === format);
+    for (const component of [item, ...Object.values(item.components)]) for (const asset of [component, ...component.variants]) {
+      for (const type of formats) if (type !== format) { delete asset[type]; delete asset[type + '_bytes']; }
+    }
+  }
+  const { writeFile } = await import('node:fs/promises');
+  const catalogPath = path.join(destination, 'catalog.json');
+  try { const existing = await realpath(catalogPath); if (!existing.startsWith(resolved + path.sep)) throw new Error('catalog.json points outside destination.'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  await writeFile(catalogPath, JSON.stringify(catalog, null, 2) + '\n');
+  console.log(`Copied ${items.length} designs and ${paths.size} files to ${destination}. Set assetsBase to its public URL.`);
+}
+
+if (process.argv[1] && await realpath(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).catch(error => { console.error(error.message); process.exitCode = 1; });
+}

package/lib/index.d.ts

@@ -0,0 +1,74 @@
+// Generated design/capability types; edit scripts/build-library.mjs.
+export type DesignName = "butterfly-panel-red" | "floral-bird-panel-blue" | "floral-bird-panel-left" | "floral-bird-panel-right" | "gold-leaf-scroll" | "gold-quatrefoil-vine" | "interlocking-ribbon" | "plate-01-linked-scrolls" | "plate-02-stepped-ribbon" | "plate-03-spiral-bands" | "plate-04-heart-and-diamond" | "plate-05-blue-curls" | "plate-06-paired-red-scrolls" | "plate-07-blue-heart-leaves" | "plate-08-diagonal-cross" | "plate-09-interlaced-knot" | "plate-10-blue-palmettes" | "plate-11-acanthus-scroll" | "plate-12-arched-diamonds" | "plate-13-leaf-and-flower-vine" | "plate-14-crossed-diamonds" | "plate-15-diamond-square" | "plate-16-stepped-corner" | "plate-17-stepped-arches" | "plate-18-fan-palmettes" | "plate-19-cream-scrolls" | "plate-20-segmented-medallions" | "plate-21-green-flower-medallions" | "plate-22-white-petal-grid" | "plate-23-crossed-ribbon-knots" | "plate-24-gold-ring-scrolls" | "plate-25-greek-crosses" | "plate-26-eight-petal-rosette" | "plate-27-blue-flower-medallions" | "plate-28-angular-blue-meander" | "plate-29-red-acanthus" | "plate-30-layered-palmettes" | "plate-31-alternating-florets" | "plate-32-linked-ovals" | "plate-33-leaf-scrolls" | "plate-34-nested-fans" | "plate-35-crossed-white-stems" | "plate-36-greek-key" | "plate-37-diamond-scroll" | "plate-38-diagonal-meander" | "red-berry-vine" | "red-rosette-vine" | "red-trefoil-vine" | "spiral-ribbon-column";
+export type RepeatDesignName = "gold-leaf-scroll" | "gold-quatrefoil-vine" | "interlocking-ribbon" | "plate-01-linked-scrolls" | "plate-02-stepped-ribbon" | "plate-03-spiral-bands" | "plate-04-heart-and-diamond" | "plate-05-blue-curls" | "plate-06-paired-red-scrolls" | "plate-07-blue-heart-leaves" | "plate-08-diagonal-cross" | "plate-09-interlaced-knot" | "plate-10-blue-palmettes" | "plate-12-arched-diamonds" | "plate-13-leaf-and-flower-vine" | "plate-14-crossed-diamonds" | "plate-15-diamond-square" | "plate-17-stepped-arches" | "plate-18-fan-palmettes" | "plate-19-cream-scrolls" | "plate-20-segmented-medallions" | "plate-21-green-flower-medallions" | "plate-22-white-petal-grid" | "plate-23-crossed-ribbon-knots" | "plate-24-gold-ring-scrolls" | "plate-25-greek-crosses" | "plate-26-eight-petal-rosette" | "plate-27-blue-flower-medallions" | "plate-28-angular-blue-meander" | "plate-29-red-acanthus" | "plate-30-layered-palmettes" | "plate-31-alternating-florets" | "plate-32-linked-ovals" | "plate-33-leaf-scrolls" | "plate-34-nested-fans" | "plate-35-crossed-white-stems" | "plate-38-diagonal-meander" | "red-berry-vine" | "red-rosette-vine" | "red-trefoil-vine";
+export type WholeDesignName = "butterfly-panel-red" | "floral-bird-panel-blue" | "floral-bird-panel-left" | "floral-bird-panel-right" | "plate-11-acanthus-scroll" | "plate-16-stepped-corner" | "plate-36-greek-key" | "plate-37-diamond-scroll" | "spiral-ribbon-column";
+export type Category = "animals" | "botanical" | "floral" | "geometric" | "knotwork" | "ribbons" | "scrollwork";
+export type OrnamentUse = 'frame' | 'divider' | 'image';
+export type Format = 'auto' | 'svg' | 'webp' | 'png';
+export type Orientation = 'original' | 'horizontal' | 'vertical';
+export interface RasterVariant {
+  readonly png: string; readonly webp: string;
+  readonly width: number; readonly height: number;
+  readonly max_dimension?: number; readonly rendered_max_dimension?: number;
+  readonly png_bytes: number; readonly webp_bytes: number;
+}
+export interface Asset extends RasterVariant {
+  readonly svg?: string; readonly viewbox?: readonly number[];
+  readonly variants: readonly RasterVariant[];
+  readonly repeat_axis?: 'x' | 'y' | 'none';
+  readonly repeat_ratio?: number; readonly slice_pixels?: number;
+}
+export interface Ornament extends Asset {
+  readonly name: DesignName; readonly description: string;
+  readonly categories: readonly Category[]; readonly subjects: readonly string[];
+  readonly colors: readonly string[]; readonly facing: string; readonly composition: string;
+  readonly kind: 'standalone' | 'repeat-tile'; readonly derivation: string;
+  readonly uses: readonly OrnamentUse[]; readonly formats: readonly Exclude<Format, 'auto'>[];
+  readonly components: Readonly<Partial<Record<'border_image' | 'corner' | 'rotated_tile' | 'reference_crop', Asset>>>;
+  readonly border_image_slice_percent?: number; readonly reference?: string;
+}
+export interface RepeatOrnament extends Ornament {
+  readonly name: RepeatDesignName; readonly kind: 'repeat-tile';
+  readonly uses: readonly ('frame' | 'divider')[]; readonly repeat_axis: 'x' | 'y';
+  readonly repeat_ratio: number; readonly border_image_slice_percent: number;
+}
+export interface WholeOrnament extends Ornament {
+  readonly name: WholeDesignName; readonly kind: 'standalone';
+  readonly uses: readonly 'image'[]; readonly repeat_axis: 'none';
+}
+export interface CommonOptions {
+  size?: number; format?: Format; pixelRatio?: number; assetsBase?: string;
+}
+export interface FrameOptions extends CommonOptions { design: RepeatDesignName; }
+export interface DividerOptions extends CommonOptions { design: RepeatDesignName; orientation?: Orientation; length?: number | string; }
+export interface ImageOptions extends CommonOptions { design: WholeDesignName; alt?: string; }
+export interface SelectionFilters {
+  use?: OrnamentUse; categories?: readonly Category[]; subjects?: readonly string[];
+  colors?: readonly string[]; query?: string;
+}
+export interface ResolvedOrnament {
+  design: DesignName; use: OrnamentUse; axis?: 'x' | 'y'; size: number;
+  className: string; style: Record<string, string>; attributes: Record<string, string>;
+  asset: { path: string; url: string; format: Exclude<Format, 'auto'>; width: number; height: number; resolutionLimited: boolean; };
+}
+export interface OrnamentController<Options> {
+  readonly element: HTMLElement;
+  readonly configuration: ResolvedOrnament;
+  update(options: Partial<Options>): OrnamentController<Options>;
+  destroy(): void;
+}
+export declare const version: string;
+export declare const defaultAssetsBase: string;
+export declare const ornaments: readonly Ornament[];
+export declare function getOrnament(name: RepeatDesignName): RepeatOrnament;
+export declare function getOrnament(name: WholeDesignName): WholeOrnament;
+export declare function getOrnament(name: string): Ornament;
+export declare function findOrnaments(filters: SelectionFilters & { use: 'frame' | 'divider' }): RepeatOrnament[];
+export declare function findOrnaments(filters: SelectionFilters & { use: 'image' }): WholeOrnament[];
+export declare function findOrnaments(filters?: SelectionFilters): Ornament[];
+export declare function resolveOrnament(use: 'frame', options: FrameOptions): ResolvedOrnament;
+export declare function resolveOrnament(use: 'divider', options: DividerOptions): ResolvedOrnament;
+export declare function resolveOrnament(use: 'image', options: ImageOptions): ResolvedOrnament;
+export declare function createFrame(element: HTMLElement, options: FrameOptions): OrnamentController<FrameOptions>;
+export declare function createDivider(element: HTMLElement, options: DividerOptions): OrnamentController<DividerOptions>;
+export declare function createOrnamentImage(element: HTMLImageElement, options: ImageOptions): OrnamentController<ImageOptions>;

package/lib/index.js

@@ -0,0 +1,3 @@
+export { ornaments, version, defaultAssetsBase } from './catalog.js';
+export { getOrnament, findOrnaments, resolveOrnament } from './resolve.js';
+export { createFrame, createDivider, createOrnamentImage } from './vanilla.js';

package/lib/react.d.ts

@@ -0,0 +1,9 @@
+import type { CSSProperties, ForwardRefExoticComponent, RefAttributes, HTMLAttributes, ImgHTMLAttributes } from 'react';
+import type { FrameOptions, DividerOptions, ImageOptions } from './index.js';
+export type OrnamentStyle = CSSProperties & { [key: `--${string}`]: string | number | undefined };
+export type OrnamentFrameProps = FrameOptions & Omit<HTMLAttributes<HTMLDivElement>, 'style' | 'dangerouslySetInnerHTML'> & { style?: OrnamentStyle };
+export type OrnamentDividerProps = DividerOptions & Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'style' | 'dangerouslySetInnerHTML'> & { style?: OrnamentStyle; children?: never };
+export type OrnamentImageProps = ImageOptions & Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'srcSet' | 'sizes' | 'height' | 'width' | 'alt' | 'children' | 'style' | 'dangerouslySetInnerHTML'> & { style?: OrnamentStyle; children?: never };
+export declare const OrnamentFrame: ForwardRefExoticComponent<OrnamentFrameProps & RefAttributes<HTMLDivElement>>;
+export declare const OrnamentDivider: ForwardRefExoticComponent<OrnamentDividerProps & RefAttributes<HTMLDivElement>>;
+export declare const OrnamentImage: ForwardRefExoticComponent<OrnamentImageProps & RefAttributes<HTMLImageElement>>;

package/lib/react.js

@@ -0,0 +1,33 @@
+'use client';
+import { createElement, forwardRef } from 'react';
+import { resolveOrnament } from './resolve.js';
+
+const sharedKeys = ['design', 'size', 'format', 'pixelRatio', 'assetsBase'];
+function render(use, tag, props, ref) {
+  const options = {}, html = { ...props };
+  const keys = [...sharedKeys, ...(use === 'divider' ? ['orientation', 'length'] : use === 'image' ? ['alt'] : [])];
+  for (const key of keys) {
+    if (Object.hasOwn(html, key)) options[key] = html[key];
+    delete html[key];
+  }
+  // Catch misplaced library props rather than leaking them onto the DOM.
+  for (const key of ['orientation', 'length', 'alt']) {
+    if (key in html) throw new TypeError(`${key} is not supported by Ornament${use[0].toUpperCase() + use.slice(1)}.`);
+  }
+  if (use !== 'frame' && html.children != null) throw new TypeError('Only OrnamentFrame accepts children.');
+  if (html.dangerouslySetInnerHTML != null) throw new TypeError('Use ordinary children inside OrnamentFrame.');
+  if (use === 'image' && ['src', 'srcSet', 'sizes', 'width', 'height'].some(key => key in html)) throw new TypeError('OrnamentImage selects its source and proportions; use design and size.');
+  const configuration = resolveOrnament(use, options);
+  const className = [configuration.className, html.className].filter(Boolean).join(' ');
+  const style = { ...html.style, ...configuration.style };
+  const attributes = { ...configuration.attributes };
+  if (use === 'divider' && html['aria-hidden'] !== undefined) attributes['aria-hidden'] = html['aria-hidden'];
+  return createElement(tag, { ...html, ...attributes, className, style, ref });
+}
+
+export const OrnamentFrame = forwardRef((props, ref) => render('frame', 'div', props, ref));
+export const OrnamentDivider = forwardRef((props, ref) => render('divider', 'div', props, ref));
+export const OrnamentImage = forwardRef((props, ref) => render('image', 'img', props, ref));
+OrnamentFrame.displayName = 'OrnamentFrame';
+OrnamentDivider.displayName = 'OrnamentDivider';
+OrnamentImage.displayName = 'OrnamentImage';

package/lib/resolve.js

@@ -0,0 +1,118 @@
+import { ornaments, defaultAssetsBase } from './catalog.js';
+
+const byName = new Map(ornaments.map(item => [item.name, item]));
+const defaults = { frame: 32, divider: 24, image: 256 };
+const optionKeys = {
+  frame: new Set(['design', 'size', 'format', 'pixelRatio', 'assetsBase']),
+  divider: new Set(['design', 'size', 'format', 'pixelRatio', 'assetsBase', 'orientation', 'length']),
+  image: new Set(['design', 'size', 'format', 'pixelRatio', 'assetsBase', 'alt'])
+};
+
+export function getOrnament(name) {
+  const item = byName.get(name);
+  if (!item) throw new RangeError(`Unknown ornament design: ${String(name)}. Use findOrnaments() to select a design.`);
+  return item;
+}
+
+export function findOrnaments({ use, categories = [], subjects = [], colors = [], query = '' } = {}) {
+  if (use !== undefined && !Object.hasOwn(defaults, use)) throw new RangeError('use must be frame, divider, or image.');
+  for (const values of [categories, subjects, colors]) {
+    if (!Array.isArray(values) || values.some(value => typeof value !== 'string')) throw new TypeError('Selection filters must be arrays of strings.');
+  }
+  if (typeof query !== 'string') throw new TypeError('query must be a string.');
+  const tokens = query.toLowerCase().trim().split(/\s+/).filter(Boolean);
+  return ornaments.filter(item => (!use || item.uses.includes(use))
+    && categories.every(value => item.categories.includes(value))
+    && subjects.every(value => item.subjects.includes(value))
+    && colors.every(value => item.colors.includes(value))
+    && tokens.every(token => [item.name, item.description, ...item.categories, ...item.subjects, ...item.colors].join(' ').toLowerCase().includes(token)));
+}
+
+function positive(value, name) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) throw new RangeError(`${name} must be a finite positive number.`);
+  return value;
+}
+
+function lengthValue(value) {
+  if (typeof value === 'number') return `${positive(value, 'length')}px`;
+  // A deliberately shared browser/server grammar, without browser globals.
+  // For container-relative layouts use %, vw/vh, or a supported CSS length.
+  if (typeof value !== 'string' || !/^(?:\d+(?:\.\d+)?|\.\d+)(?:px|%|em|rem|vw|vh|vmin|vmax|svw|svh|lvw|lvh|dvw|dvh|ch|ex|cm|mm|in|pt|pc)$/.test(value) || parseFloat(value) <= 0) {
+    throw new RangeError('length must be a positive pixel number or CSS length such as "100%", "240px", or "20rem".');
+  }
+  return value;
+}
+
+function imageUrl(path, base) {
+  if (typeof base !== 'string' || !base || /[\s?#\\]/.test(base)) throw new TypeError('assetsBase must be an absolute http(s) URL or a root-relative public path without a query or fragment.');
+  if (/^https?:\/\//.test(base)) {
+    const parsed = new URL(base);
+    if (parsed.username || parsed.password) throw new TypeError('assetsBase must not contain credentials.');
+  } else if (!base.startsWith('/') || base.startsWith('//')) {
+    throw new TypeError('assetsBase must be an absolute http(s) URL or a root-relative public path, such as "/ornaments/".');
+  }
+  return base.replace(/\/+$/, '') + '/' + path;
+}
+
+// Pure and deterministic: used by React, vanilla, SSR and advanced integrations.
+// Does not access the DOM, perform requests, or mutate the catalog/options.
+export function resolveOrnament(use, options) {
+  if (!Object.hasOwn(defaults, use)) throw new RangeError('use must be frame, divider, or image.');
+  if (!options || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('An options object with a design is required.');
+  for (const key of Object.keys(options)) {
+    if (!optionKeys[use].has(key)) throw new TypeError(`Unsupported ${use} option: ${key}.`);
+  }
+  const item = getOrnament(options.design);
+  if (!item.uses.includes(use)) throw new RangeError(`${item.name} cannot be used as ${use}; supported uses: ${item.uses.join(', ')}.`);
+  const size = positive(options.size === undefined ? defaults[use] : options.size, 'size');
+  const density = positive(options.pixelRatio === undefined ? 2 : options.pixelRatio, 'pixelRatio');
+  let axis, source = item;
+  if (use === 'frame') source = item.components.border_image;
+  if (use === 'divider') {
+    const orientation = options.orientation === undefined ? 'original' : options.orientation;
+    if (!['original', 'horizontal', 'vertical'].includes(orientation)) throw new RangeError('orientation must be original, horizontal, or vertical.');
+    axis = orientation === 'original' ? item.repeat_axis : orientation === 'horizontal' ? 'x' : 'y';
+    if (axis !== item.repeat_axis) source = item.components.rotated_tile;
+  }
+  let format = options.format === undefined ? 'auto' : options.format;
+  if (format === 'auto') format = item.derivation === 'vector-reconstruction' && source.svg ? 'svg' : 'webp';
+  if (!['svg', 'png', 'webp'].includes(format) || !source[format]) throw new RangeError(`${item.name} does not support format ${String(format)} for ${use}. Available: ${item.formats.join(', ')}.`);
+  let selected = source, required;
+  if (use === 'frame') required = size * 100 / item.border_image_slice_percent * density;
+  else if (use === 'divider') required = size * Math.max(1, item.repeat_ratio) * density;
+  else required = size * Math.max(1, source.width / source.height) * density;
+  if (!Number.isFinite(required)) throw new RangeError('size and pixelRatio produce an invalid resolution.');
+  if (format !== 'svg') {
+    const candidates = [...source.variants, source].sort((a, b) => Math.max(a.width, a.height) - Math.max(b.width, b.height));
+    selected = candidates.find(asset => Math.max(asset.width, asset.height) + 1e-8 >= required) ?? source;
+  }
+  const path = selected[format];
+  const url = imageUrl(path, options.assetsBase === undefined ? defaultAssetsBase : options.assetsBase);
+  const style = { '--ornament-size': `${size}px` };
+  const attributes = {};
+  if (use === 'image') {
+    if (options.alt !== undefined && typeof options.alt !== 'string') throw new TypeError('alt must be a string.');
+    attributes.src = url;
+    attributes.alt = options.alt ?? '';
+  } else {
+    style['--ornament-image'] = `url(${JSON.stringify(url)})`;
+    if (use === 'frame') style['--ornament-slice'] = `${item.border_image_slice_percent}%`;
+    else {
+      style['--ornament-ratio'] = String(item.repeat_ratio);
+      style['--ornament-length'] = lengthValue(options.length === undefined ? (axis === 'x' ? '100%' : 256) : options.length);
+      attributes['data-axis'] = axis;
+      attributes['aria-hidden'] = 'true';
+    }
+  }
+  return {
+    design: item.name, use, axis, size,
+    className: use === 'image' ? 'ornament-image' : `ornament-${use}`,
+    style, attributes,
+    asset: {
+      path, url, format,
+      width: format === 'svg' ? source.viewbox[2] : selected.width,
+      height: format === 'svg' ? source.viewbox[3] : selected.height,
+      resolutionLimited: format !== 'svg' && Math.max(selected.width, selected.height) + 1e-8 < required
+    }
+  };
+}

package/lib/styles.d.ts

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

package/lib/vanilla.js

@@ -0,0 +1,57 @@
+import { resolveOrnament } from './resolve.js';
+
+const attached = new WeakMap();
+
+function attach(element, use, initial) {
+  if (!element || element.nodeType !== 1 || element.namespaceURI !== 'http://www.w3.org/1999/xhtml' || !element.style || !element.classList) throw new TypeError('An HTML element is required.');
+  if (use === 'image' && element.tagName !== 'IMG') throw new TypeError('createOrnamentImage requires an img element.');
+  if (use !== 'image' && ['AREA', 'BASE', 'BR', 'COL', 'EMBED', 'HR', 'IMG', 'INPUT', 'LINK', 'META', 'PARAM', 'SOURCE', 'TRACK', 'WBR', 'CANVAS', 'IFRAME', 'VIDEO', 'AUDIO'].includes(element.tagName)) throw new TypeError(`${use} requires a container element such as div or article.`);
+  if (attached.has(element)) throw new Error('This element already has an ornament controller. Destroy it before attaching another.');
+  let options = { ...initial }, current = resolveOrnament(use, initial), destroyed = false;
+  const previousClass = element.classList.contains(current.className);
+  const styles = new Map(Object.keys(current.style).map(key => [key, { value: element.style.getPropertyValue(key), priority: element.style.getPropertyPriority(key) }]));
+  const attributes = new Map(Object.keys(current.attributes).map(key => [key, element.getAttribute(key)]));
+  function paint(result) {
+    element.classList.add(result.className);
+    for (const [key, value] of Object.entries(result.style)) element.style.setProperty(key, value);
+    for (const [key, value] of Object.entries(result.attributes)) element.setAttribute(key, value);
+  }
+  const controller = {
+    element,
+    get configuration() { return resolveOrnament(use, options); },
+    update(patch) {
+      if (destroyed) throw new Error('Cannot update a destroyed ornament controller.');
+      if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new TypeError('update requires a partial options object.');
+      const nextOptions = { ...options, ...patch };
+      const next = resolveOrnament(use, nextOptions); // Validate completely before touching the DOM.
+      paint(next);
+      options = nextOptions;
+      current = next;
+      return controller;
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      attached.delete(element);
+      // Restore only values still owned by this controller; retain external edits.
+      if (!previousClass) element.classList.remove(current.className);
+      for (const [key, before] of styles) {
+        if (element.style.getPropertyValue(key) !== current.style[key]) continue;
+        if (before.value) element.style.setProperty(key, before.value, before.priority);
+        else element.style.removeProperty(key);
+      }
+      for (const [key, before] of attributes) {
+        if (element.getAttribute(key) !== current.attributes[key]) continue;
+        if (before === null) element.removeAttribute(key);
+        else element.setAttribute(key, before);
+      }
+    }
+  };
+  attached.set(element, controller);
+  paint(current);
+  return controller;
+}
+
+export const createFrame = (element, options) => attach(element, 'frame', options);
+export const createDivider = (element, options) => attach(element, 'divider', options);
+export const createOrnamentImage = (element, options) => attach(element, 'image', options);

package/ornaments.css

@@ -0,0 +1,63 @@
+/* Shared usage contract. Use absolute image URLs, or paths relative to this stylesheet. */
+.ornament-frame {
+  box-sizing: border-box;
+  border: var(--ornament-size, 32px) solid transparent;
+  border-image-source: var(--ornament-image, none);
+  border-image-slice: var(--ornament-slice, 21.42857142857143%);
+  /* Partial periods cannot match a designed corner. Always fit whole units. */
+  border-image-repeat: round;
+}
+
+.ornament-divider {
+  --ornament-period: calc(var(--ornament-size, 24px) * var(--ornament-ratio, 2.6666666666666665));
+  display: block;
+  position: relative;
+  width: var(--ornament-length, 100%);
+  height: var(--ornament-size, 24px);
+}
+
+.ornament-divider::before {
+  content: "";
+  position: absolute;
+  left: 50%;
+  top: 0;
+  transform: translateX(-50%);
+  width: 100%;
+  height: 100%;
+  background-image: var(--ornament-image, none);
+  /* Older browsers fit complete tiles by adjusting their length. */
+  background-repeat: round no-repeat;
+  background-size: var(--ornament-period) var(--ornament-size, 24px);
+}
+
+.ornament-divider[data-axis="y"] {
+  width: var(--ornament-size, 24px);
+  height: var(--ornament-length, 256px);
+}
+
+.ornament-divider[data-axis="y"]::before {
+  left: 0;
+  top: 50%;
+  transform: translateY(-50%);
+  background-repeat: no-repeat round;
+  background-size: var(--ornament-size, 24px) var(--ornament-period);
+}
+
+@supports (width: round(down, 100%, 64px)) {
+  .ornament-divider::before {
+    /* Keep contiguous complete units; spare space stays outside the artwork. */
+    width: round(down, 100%, var(--ornament-period));
+  }
+  .ornament-divider[data-axis="y"]::before {
+    width: 100%;
+    height: round(down, 100%, var(--ornament-period));
+  }
+}
+
+.ornament-image {
+  display: block;
+  height: var(--ornament-size, 256px);
+  width: auto;
+  max-width: 100%;
+  object-fit: contain;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@ranx729/medieval-ornaments",
+  "version": "0.1.0",
+  "description": "Categorized medieval ornaments with normalized frames, repeating dividers and whole decorations for JavaScript and React",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": { "type": "git", "url": "git+https://github.com/adrian729/medieval-ornaments.git" },
+  "homepage": "https://adrian729.github.io/medieval-ornaments/",
+  "bugs": { "url": "https://github.com/adrian729/medieval-ornaments/issues" },
+  "keywords": ["medieval", "ornament", "border", "divider", "react", "vanilla", "decoration"],
+  "exports": {
+    ".": { "types": "./lib/index.d.ts", "import": "./lib/index.js" },
+    "./react": { "types": "./lib/react.d.ts", "import": "./lib/react.js" },
+    "./styles.css": { "types": "./lib/styles.d.ts", "default": "./ornaments.css" },
+    "./catalog.json": "./lib/catalog.json",
+    "./svg/*": "./svg/*",
+    "./png/*": "./png/*",
+    "./webp/*": "./webp/*",
+    "./package.json": "./package.json"
+  },
+  "bin": { "medieval-ornaments": "./lib/cli.js" },
+  "files": ["lib", "ornaments.css", "svg", "png", "webp", "docs/INTEGRATION.md", "ASSET-RIGHTS.md", "SELECTION.md", "USAGE.md"],
+  "sideEffects": ["**/*.css"],
+  "peerDependencies": { "react": ">=18 <20" },
+  "peerDependenciesMeta": { "react": { "optional": true } },
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "node scripts/build-library.mjs",
+    "build:browser": "node scripts/build-browser.mjs",
+    "prepack": "node scripts/build-library.mjs",
+    "test": "node --test tests/*.test.mjs",
+    "test:types": "tsc --noEmit --strict --noUncheckedSideEffectImports --module nodenext --target es2022 --jsx react-jsx tests/types.tsx",
+    "test:integration": "node tests/integration.mjs"
+  },
+  "publishConfig": { "access": "public" },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "typescript": "7.0.2",
+    "vite": "8.3.2"
+  }
+}