@scenography/plugin-artwork 0.2.0

package/dist/data-BsI0PbuK.mjs

@@ -0,0 +1,87 @@
+import { eachPropIs, existsProp, fail, isFiniteNumber, isIntegerNumber, isMeasure, isNonNegativeNumber, isObject, isOneOf, isPositiveNumber, isString, isVec2, isVec3, propIs, validate, when } from "@scenography/scene";
+import { allEdgeNames } from "@scenography/plugin-wall/data";
+//#region src/data/artwork.ts
+/** Default visibility when a label/card doesn't specify its own `fields`. */
+const DEFAULT_ARTWORK_FIELDS = [
+	"title",
+	"technique",
+	"dimensions",
+	"availability"
+];
+//#endregion
+//#region src/data/validate.ts
+const AVAILABILITY = new Set([
+	"for-sale",
+	"sold",
+	"not-for-sale"
+]);
+const ARTWORK_FIELDS = new Set([
+	"title",
+	"author",
+	"year",
+	"technique",
+	"dimensions",
+	"availability"
+]);
+const LABEL_SIDES = new Set([
+	"below",
+	"left",
+	"right"
+]);
+const LOCATION_TYPES = new Set(["wall", "floating"]);
+const locationOfType = (type) => (artwork) => isObject(artwork.location) && artwork.location.type === type;
+/**
+* Validate one artwork. `edgeNames` is the set of wall-edge names in the scene,
+* used to check `location.edge` references. Returns every problem found, in
+* order, with paths relative to the artwork (the caller scopes them).
+*/
+const validateArtwork = (artwork, edgeNames) => validate([
+	existsProp("id", "Artwork is missing an id."),
+	existsProp("src", "Artwork is missing a src."),
+	existsProp("size", "Artwork is missing a size."),
+	propIs("size", isVec2, "size must be [width, height]."),
+	propIs("depth", isNonNegativeNumber, "depth must be a non-negative number."),
+	propIs("year", isIntegerNumber, "year must be an integer."),
+	propIs("href", isString, "href must be a string."),
+	propIs("availability", isOneOf(AVAILABILITY), "availability must be 'for-sale', 'sold' or 'not-for-sale'."),
+	propIs("infoRadius", isPositiveNumber, "infoRadius must be a positive number."),
+	propIs("label.side", isOneOf(LABEL_SIDES), "side must be 'below', 'left' or 'right'."),
+	propIs("label.fields", Array.isArray, "fields must be an array."),
+	eachPropIs("label.fields", isOneOf(ARTWORK_FIELDS), (field) => `unknown field "${String(field)}".`),
+	propIs("label.scale", isPositiveNumber, "scale must be a positive number."),
+	propIs("label.offset", isVec2, "offset must be [x, y]."),
+	propIs("frame.width", isFiniteNumber, "width must be a finite number."),
+	propIs("frame.depth", isFiniteNumber, "depth must be a finite number."),
+	when((a) => a.frame?.texture !== void 0, existsProp("frame.texture.src", "frame texture is missing a src.")),
+	propIs("frame.passepartout.width", isFiniteNumber, "passepartout width must be a finite number."),
+	existsProp("location", "Artwork is missing a location."),
+	propIs("location", isObject, "location must be an object."),
+	when(locationOfType("wall"), existsProp("location.edge"), propIs("location.edge", (edge) => isString(edge) && edgeNames.has(edge), (edge) => `references unknown edge "${String(edge)}".`), existsProp("location.position"), propIs("location.position", isMeasure, "position must be a number or a percentage string."), propIs("location.height", isMeasure, "height must be a number or a percentage string.")),
+	when(locationOfType("floating"), existsProp("location.point"), propIs("location.point", isVec3, "point must be [x, y, z].")),
+	when((a) => isObject(a.location) && !isOneOf(LOCATION_TYPES)(a.location.type), fail("location.type", "unknown location type."))
+])(artwork);
+/**
+* Validate an artwork against its scene: resolves the set of valid wall-edge
+* names from the scene's walls (the wall plugin's data half) so `location.edge`
+* references are checked. Floating pieces don't need any wall.
+*/
+const validateArtworkInScene = (artwork, ctx) => {
+	const walls = ctx.scene.walls ?? [];
+	return validateArtwork(artwork, new Set(allEdgeNames(walls)));
+};
+//#endregion
+//#region src/data/plugin.ts
+/**
+* The data half of the artwork plugin: owns the `artworks` scene key (a
+* collection) and validates each piece — including that a wall-hung piece
+* references a real wall edge. Pure — no three.js.
+*/
+const artworkData = {
+	kind: "artworks",
+	cardinality: "many",
+	validate: (artwork, ctx) => validateArtworkInScene(artwork, ctx)
+};
+//#endregion
+export { DEFAULT_ARTWORK_FIELDS as i, validateArtwork as n, validateArtworkInScene as r, artworkData as t };
+
+//# sourceMappingURL=data-BsI0PbuK.mjs.map

package/dist/data-BsI0PbuK.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-BsI0PbuK.mjs","names":[],"sources":["../src/data/artwork.ts","../src/data/validate.ts","../src/data/plugin.ts"],"sourcesContent":["import type { Measure, SurfaceTexture, Vec2, Vec3 } from \"@scenography/scene\";\n\n/**\n * Where an artwork is placed. Extensible via `type`; today a piece either hangs\n * on a named wall edge or floats freely. Future element types (floor, ceiling…)\n * add new variants here.\n */\nexport type ArtworkLocation =\n  | {\n      type: \"wall\";\n      /** Name of the `NamedEdge` to hang on. */\n      edge: string;\n      /** Position along the edge: a number is units from the edge start, `'50%'` is a fraction. */\n      position: Measure;\n      /**\n       * Vertical placement: a number is an absolute world Y, `'50%'` is a\n       * fraction of the wall height. Omitted defaults to the camera's eye height.\n       */\n      height?: Measure;\n      /**\n       * Which face of the wall the piece shows on, relative to the edge\n       * direction. `'right'` (default) is the right-hand side when walking the\n       * edge from its start vertex to its end vertex.\n       */\n      side?: \"right\" | \"left\";\n    }\n  | {\n      type: \"floating\";\n      /** World position `[x, y, z]`. */\n      point: Vec3;\n      /** Y-axis rotation in radians. Defaults to `0`. */\n      yaw?: number;\n    };\n\n/**\n * A passepartout (mat) sitting between the frame and the image: a flat border\n * that insets the image. Only meaningful when the artwork has a `frame`.\n */\nexport interface Passepartout {\n  /** Mat border width around the image, in world units. Defaults to `6`. */\n  width?: number;\n  /** Mat color (CSS). Defaults to an off-white. */\n  color?: string;\n}\n\n/**\n * A frame around an artwork. By default it's four flat bars rendered with a\n * solid `color` or a `texture` (e.g. wood). For an ornate, sculpted frame, point\n * `model` at an external glTF/GLB instead. A `passepartout` mat can sit between\n * the frame and the image.\n */\nexport interface Frame {\n  /** Border width (how wide the frame face is), in world units. Defaults to `5`. */\n  width?: number;\n  /** How far the frame stands proud of the artwork face, in world units. Defaults to `3`. */\n  depth?: number;\n  /** Frame color (CSS). Defaults to a dark tone. Ignored when `texture` or `model` is set. */\n  color?: string;\n  /** Surface texture (e.g. wood); takes visual precedence over `color`. */\n  texture?: SurfaceTexture;\n  /** External glTF/GLB model for an ornate frame; replaces the generated bars. */\n  model?: string;\n  /** Passepartout mat between the frame and the image. */\n  passepartout?: Passepartout;\n}\n\n/**\n * Commercial status of a piece. Gallery convention: a colored dot signals\n * availability. The dot's color is presentation (decided by the renderer), not\n * data — this is the state it derives from.\n */\nexport type Availability = \"for-sale\" | \"sold\" | \"not-for-sale\";\n\n/**\n * The fields a label/info card can show, identified by name. A `fields` array\n * toggles which are visible; the render order is fixed (it is not the array\n * order): title, then author/year, then technique + dimensions on one line, with\n * availability shown as a corner dot. Shared by the physical label (engine) and\n * the overlay info card.\n */\nexport type ArtworkField = \"title\" | \"author\" | \"year\" | \"technique\" | \"dimensions\" | \"availability\";\n\n/** Default visibility when a label/card doesn't specify its own `fields`. */\nexport const DEFAULT_ARTWORK_FIELDS: readonly ArtworkField[] = [\n  \"title\",\n  \"technique\",\n  \"dimensions\",\n  \"availability\",\n];\n\n/**\n * A physical wall label (cartela) materialized next to the piece. Its presence\n * is the opt-in; the engine renders it from the artwork's own data.\n */\nexport interface ArtworkLabel {\n  /** Where the label sits relative to the piece. Defaults to `'below'`. */\n  side?: \"below\" | \"left\" | \"right\";\n  /** Which fields to show. Defaults to `DEFAULT_ARTWORK_FIELDS`. */\n  fields?: ArtworkField[];\n  /**\n   * Size multiplier over the real physical size (24pt title etc). Defaults to\n   * `1` (true to life), but a real cartela is only a few cm tall — tiny and hard\n   * to read/click at gallery scale — so bump this (e.g. `3`) for legibility.\n   */\n  scale?: number;\n  /**\n   * Fine-tune the placement with an `[x, y]` shift in world units, added on top\n   * of the `side` position (the frame is already cleared). `x` runs along the\n   * wall (right is positive), `y` is vertical (up is positive).\n   */\n  offset?: Vec2;\n}\n\n/** A framed image placed somewhere in the scene. */\nexport interface Artwork {\n  id: string;\n  location: ArtworkLocation;\n  /** Image URL/path to display. */\n  src: string;\n  /** `[width, height]` of the artwork, in world units. */\n  size: Vec2;\n  /**\n   * Box depth (volume) in world units: the piece is a box with the image on the\n   * front and white sides/back. Defaults to `2`.\n   */\n  depth?: number;\n  /** Optional frame around the artwork. */\n  frame?: Frame;\n  title?: string;\n  technique?: string;\n  /** Author / artist name. */\n  author?: string;\n  /** Year the piece was made. */\n  year?: number;\n  /**\n   * Real-world dimensions for display, e.g. `'92 × 73 cm'`. Distinct from `size`,\n   * which is in world units.\n   */\n  dimensions?: string;\n  /** Commercial status; drives the availability dot. */\n  availability?: Availability;\n  /** Long-form caption / catalog entry, shown in the expanded info panel. */\n  description?: string;\n  /**\n   * External URL for the piece (a catalog page, or a marketplace listing when\n   * it's for sale). Surfaced as a link in the expanded info panel.\n   */\n  href?: string;\n  /** When present, a physical wall label is materialized next to the piece. */\n  label?: ArtworkLabel;\n  /**\n   * Max distance (world units) from which the piece can be clicked to open its\n   * info panel. A gate so far-away pieces aren't interactive. Absent = no gate.\n   */\n  infoRadius?: number;\n}\n\ndeclare module \"@scenography/scene\" {\n  interface Scene {\n    /** Framed images placed in the space — provided by `@scenography/plugin-artwork`. */\n    artworks?: Artwork[];\n  }\n}\n","import {\n  eachPropIs,\n  existsProp,\n  fail,\n  isFiniteNumber,\n  isIntegerNumber,\n  isMeasure,\n  isNonNegativeNumber,\n  isObject,\n  isOneOf,\n  isPositiveNumber,\n  isString,\n  isVec2,\n  isVec3,\n  propIs,\n  validate,\n  when,\n  type SceneContext,\n  type ValidationResult,\n} from \"@scenography/scene\";\nimport { allEdgeNames, type Wall } from \"@scenography/plugin-wall/data\";\n\nimport type { Artwork, ArtworkField, Availability } from \"./artwork\";\n\nconst AVAILABILITY: ReadonlySet<Availability> = new Set<Availability>([\n  \"for-sale\",\n  \"sold\",\n  \"not-for-sale\",\n]);\nconst ARTWORK_FIELDS: ReadonlySet<ArtworkField> = new Set<ArtworkField>([\n  \"title\",\n  \"author\",\n  \"year\",\n  \"technique\",\n  \"dimensions\",\n  \"availability\",\n]);\nconst LABEL_SIDES: ReadonlySet<string> = new Set([\"below\", \"left\", \"right\"]);\nconst LOCATION_TYPES: ReadonlySet<string> = new Set([\"wall\", \"floating\"]);\n\nconst locationOfType =\n  (type: string) =>\n  (artwork: Artwork): boolean =>\n    isObject(artwork.location) && artwork.location.type === type;\n\n/**\n * Validate one artwork. `edgeNames` is the set of wall-edge names in the scene,\n * used to check `location.edge` references. Returns every problem found, in\n * order, with paths relative to the artwork (the caller scopes them).\n */\nexport const validateArtwork = (artwork: Artwork, edgeNames: Set<string>): ValidationResult =>\n  validate<Artwork>([\n    existsProp(\"id\", \"Artwork is missing an id.\"),\n    existsProp(\"src\", \"Artwork is missing a src.\"),\n    existsProp(\"size\", \"Artwork is missing a size.\"),\n    propIs(\"size\", isVec2, \"size must be [width, height].\"),\n    propIs(\"depth\", isNonNegativeNumber, \"depth must be a non-negative number.\"),\n    propIs(\"year\", isIntegerNumber, \"year must be an integer.\"),\n    propIs(\"href\", isString, \"href must be a string.\"),\n    propIs(\n      \"availability\",\n      isOneOf(AVAILABILITY),\n      \"availability must be 'for-sale', 'sold' or 'not-for-sale'.\",\n    ),\n    propIs(\"infoRadius\", isPositiveNumber, \"infoRadius must be a positive number.\"),\n    propIs(\"label.side\", isOneOf(LABEL_SIDES), \"side must be 'below', 'left' or 'right'.\"),\n    propIs(\"label.fields\", Array.isArray, \"fields must be an array.\"),\n    eachPropIs(\"label.fields\", isOneOf(ARTWORK_FIELDS), (field) => `unknown field \"${String(field)}\".`),\n    propIs(\"label.scale\", isPositiveNumber, \"scale must be a positive number.\"),\n    propIs(\"label.offset\", isVec2, \"offset must be [x, y].\"),\n    propIs(\"frame.width\", isFiniteNumber, \"width must be a finite number.\"),\n    propIs(\"frame.depth\", isFiniteNumber, \"depth must be a finite number.\"),\n    when(\n      (a: Artwork) => a.frame?.texture !== undefined,\n      existsProp(\"frame.texture.src\", \"frame texture is missing a src.\"),\n    ),\n    propIs(\n      \"frame.passepartout.width\",\n      isFiniteNumber,\n      \"passepartout width must be a finite number.\",\n    ),\n    existsProp(\"location\", \"Artwork is missing a location.\"),\n    propIs(\"location\", isObject, \"location must be an object.\"),\n    when(\n      locationOfType(\"wall\"),\n      existsProp(\"location.edge\"),\n      propIs(\n        \"location.edge\",\n        (edge) => isString(edge) && edgeNames.has(edge),\n        (edge) => `references unknown edge \"${String(edge)}\".`,\n      ),\n      existsProp(\"location.position\"),\n      propIs(\"location.position\", isMeasure, \"position must be a number or a percentage string.\"),\n      propIs(\"location.height\", isMeasure, \"height must be a number or a percentage string.\"),\n    ),\n    when(\n      locationOfType(\"floating\"),\n      existsProp(\"location.point\"),\n      propIs(\"location.point\", isVec3, \"point must be [x, y, z].\"),\n    ),\n    when(\n      (a: Artwork) => isObject(a.location) && !isOneOf(LOCATION_TYPES)(a.location.type),\n      fail(\"location.type\", \"unknown location type.\"),\n    ),\n  ])(artwork);\n\n/**\n * Validate an artwork against its scene: resolves the set of valid wall-edge\n * names from the scene's walls (the wall plugin's data half) so `location.edge`\n * references are checked. Floating pieces don't need any wall.\n */\nexport const validateArtworkInScene = (artwork: Artwork, ctx: SceneContext): ValidationResult => {\n  const walls = (ctx.scene as { walls?: Wall[] }).walls ?? [];\n  return validateArtwork(artwork, new Set(allEdgeNames(walls)));\n};\n","import type { DataPlugin } from \"@scenography/scene\";\n\nimport { validateArtworkInScene } from \"./validate\";\nimport type { Artwork } from \"./artwork\";\n\n/**\n * The data half of the artwork plugin: owns the `artworks` scene key (a\n * collection) and validates each piece — including that a wall-hung piece\n * references a real wall edge. Pure — no three.js.\n */\nexport const artworkData: DataPlugin<Artwork> = {\n  kind: \"artworks\",\n  cardinality: \"many\",\n  validate: (artwork, ctx) => validateArtworkInScene(artwork, ctx),\n};\n"],"mappings":";;;;AAmFA,MAAa,yBAAkD;CAC7D;CACA;CACA;CACA;AACF;;;AChEA,MAAM,eAA0C,IAAI,IAAkB;CACpE;CACA;CACA;AACF,CAAC;AACD,MAAM,iBAA4C,IAAI,IAAkB;CACtE;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;AACD,MAAM,cAAmC,IAAI,IAAI;CAAC;CAAS;CAAQ;AAAO,CAAC;AAC3E,MAAM,iBAAsC,IAAI,IAAI,CAAC,QAAQ,UAAU,CAAC;AAExE,MAAM,kBACH,UACA,YACC,SAAS,QAAQ,QAAQ,KAAK,QAAQ,SAAS,SAAS;;;;;;AAO5D,MAAa,mBAAmB,SAAkB,cAChD,SAAkB;CAChB,WAAW,MAAM,2BAA2B;CAC5C,WAAW,OAAO,2BAA2B;CAC7C,WAAW,QAAQ,4BAA4B;CAC/C,OAAO,QAAQ,QAAQ,+BAA+B;CACtD,OAAO,SAAS,qBAAqB,sCAAsC;CAC3E,OAAO,QAAQ,iBAAiB,0BAA0B;CAC1D,OAAO,QAAQ,UAAU,wBAAwB;CACjD,OACE,gBACA,QAAQ,YAAY,GACpB,4DACF;CACA,OAAO,cAAc,kBAAkB,uCAAuC;CAC9E,OAAO,cAAc,QAAQ,WAAW,GAAG,0CAA0C;CACrF,OAAO,gBAAgB,MAAM,SAAS,0BAA0B;CAChE,WAAW,gBAAgB,QAAQ,cAAc,IAAI,UAAU,kBAAkB,OAAO,KAAK,EAAE,GAAG;CAClG,OAAO,eAAe,kBAAkB,kCAAkC;CAC1E,OAAO,gBAAgB,QAAQ,wBAAwB;CACvD,OAAO,eAAe,gBAAgB,gCAAgC;CACtE,OAAO,eAAe,gBAAgB,gCAAgC;CACtE,MACG,MAAe,EAAE,OAAO,YAAY,KAAA,GACrC,WAAW,qBAAqB,iCAAiC,CACnE;CACA,OACE,4BACA,gBACA,6CACF;CACA,WAAW,YAAY,gCAAgC;CACvD,OAAO,YAAY,UAAU,6BAA6B;CAC1D,KACE,eAAe,MAAM,GACrB,WAAW,eAAe,GAC1B,OACE,kBACC,SAAS,SAAS,IAAI,KAAK,UAAU,IAAI,IAAI,IAC7C,SAAS,4BAA4B,OAAO,IAAI,EAAE,GACrD,GACA,WAAW,mBAAmB,GAC9B,OAAO,qBAAqB,WAAW,mDAAmD,GAC1F,OAAO,mBAAmB,WAAW,iDAAiD,CACxF;CACA,KACE,eAAe,UAAU,GACzB,WAAW,gBAAgB,GAC3B,OAAO,kBAAkB,QAAQ,0BAA0B,CAC7D;CACA,MACG,MAAe,SAAS,EAAE,QAAQ,KAAK,CAAC,QAAQ,cAAc,CAAC,CAAC,EAAE,SAAS,IAAI,GAChF,KAAK,iBAAiB,wBAAwB,CAChD;AACF,CAAC,CAAC,CAAC,OAAO;;;;;;AAOZ,MAAa,0BAA0B,SAAkB,QAAwC;CAC/F,MAAM,QAAS,IAAI,MAA6B,SAAS,CAAC;CAC1D,OAAO,gBAAgB,SAAS,IAAI,IAAI,aAAa,KAAK,CAAC,CAAC;AAC9D;;;;;;;;ACxGA,MAAa,cAAmC;CAC9C,MAAM;CACN,aAAa;CACb,WAAW,SAAS,QAAQ,uBAAuB,SAAS,GAAG;AACjE"}

package/dist/data-WcCPqQ_k.cjs

@@ -0,0 +1,110 @@
+let _scenography_scene = require("@scenography/scene");
+let _scenography_plugin_wall_data = require("@scenography/plugin-wall/data");
+//#region src/data/artwork.ts
+/** Default visibility when a label/card doesn't specify its own `fields`. */
+const DEFAULT_ARTWORK_FIELDS = [
+	"title",
+	"technique",
+	"dimensions",
+	"availability"
+];
+//#endregion
+//#region src/data/validate.ts
+const AVAILABILITY = new Set([
+	"for-sale",
+	"sold",
+	"not-for-sale"
+]);
+const ARTWORK_FIELDS = new Set([
+	"title",
+	"author",
+	"year",
+	"technique",
+	"dimensions",
+	"availability"
+]);
+const LABEL_SIDES = new Set([
+	"below",
+	"left",
+	"right"
+]);
+const LOCATION_TYPES = new Set(["wall", "floating"]);
+const locationOfType = (type) => (artwork) => (0, _scenography_scene.isObject)(artwork.location) && artwork.location.type === type;
+/**
+* Validate one artwork. `edgeNames` is the set of wall-edge names in the scene,
+* used to check `location.edge` references. Returns every problem found, in
+* order, with paths relative to the artwork (the caller scopes them).
+*/
+const validateArtwork = (artwork, edgeNames) => (0, _scenography_scene.validate)([
+	(0, _scenography_scene.existsProp)("id", "Artwork is missing an id."),
+	(0, _scenography_scene.existsProp)("src", "Artwork is missing a src."),
+	(0, _scenography_scene.existsProp)("size", "Artwork is missing a size."),
+	(0, _scenography_scene.propIs)("size", _scenography_scene.isVec2, "size must be [width, height]."),
+	(0, _scenography_scene.propIs)("depth", _scenography_scene.isNonNegativeNumber, "depth must be a non-negative number."),
+	(0, _scenography_scene.propIs)("year", _scenography_scene.isIntegerNumber, "year must be an integer."),
+	(0, _scenography_scene.propIs)("href", _scenography_scene.isString, "href must be a string."),
+	(0, _scenography_scene.propIs)("availability", (0, _scenography_scene.isOneOf)(AVAILABILITY), "availability must be 'for-sale', 'sold' or 'not-for-sale'."),
+	(0, _scenography_scene.propIs)("infoRadius", _scenography_scene.isPositiveNumber, "infoRadius must be a positive number."),
+	(0, _scenography_scene.propIs)("label.side", (0, _scenography_scene.isOneOf)(LABEL_SIDES), "side must be 'below', 'left' or 'right'."),
+	(0, _scenography_scene.propIs)("label.fields", Array.isArray, "fields must be an array."),
+	(0, _scenography_scene.eachPropIs)("label.fields", (0, _scenography_scene.isOneOf)(ARTWORK_FIELDS), (field) => `unknown field "${String(field)}".`),
+	(0, _scenography_scene.propIs)("label.scale", _scenography_scene.isPositiveNumber, "scale must be a positive number."),
+	(0, _scenography_scene.propIs)("label.offset", _scenography_scene.isVec2, "offset must be [x, y]."),
+	(0, _scenography_scene.propIs)("frame.width", _scenography_scene.isFiniteNumber, "width must be a finite number."),
+	(0, _scenography_scene.propIs)("frame.depth", _scenography_scene.isFiniteNumber, "depth must be a finite number."),
+	(0, _scenography_scene.when)((a) => a.frame?.texture !== void 0, (0, _scenography_scene.existsProp)("frame.texture.src", "frame texture is missing a src.")),
+	(0, _scenography_scene.propIs)("frame.passepartout.width", _scenography_scene.isFiniteNumber, "passepartout width must be a finite number."),
+	(0, _scenography_scene.existsProp)("location", "Artwork is missing a location."),
+	(0, _scenography_scene.propIs)("location", _scenography_scene.isObject, "location must be an object."),
+	(0, _scenography_scene.when)(locationOfType("wall"), (0, _scenography_scene.existsProp)("location.edge"), (0, _scenography_scene.propIs)("location.edge", (edge) => (0, _scenography_scene.isString)(edge) && edgeNames.has(edge), (edge) => `references unknown edge "${String(edge)}".`), (0, _scenography_scene.existsProp)("location.position"), (0, _scenography_scene.propIs)("location.position", _scenography_scene.isMeasure, "position must be a number or a percentage string."), (0, _scenography_scene.propIs)("location.height", _scenography_scene.isMeasure, "height must be a number or a percentage string.")),
+	(0, _scenography_scene.when)(locationOfType("floating"), (0, _scenography_scene.existsProp)("location.point"), (0, _scenography_scene.propIs)("location.point", _scenography_scene.isVec3, "point must be [x, y, z].")),
+	(0, _scenography_scene.when)((a) => (0, _scenography_scene.isObject)(a.location) && !(0, _scenography_scene.isOneOf)(LOCATION_TYPES)(a.location.type), (0, _scenography_scene.fail)("location.type", "unknown location type."))
+])(artwork);
+/**
+* Validate an artwork against its scene: resolves the set of valid wall-edge
+* names from the scene's walls (the wall plugin's data half) so `location.edge`
+* references are checked. Floating pieces don't need any wall.
+*/
+const validateArtworkInScene = (artwork, ctx) => {
+	const walls = ctx.scene.walls ?? [];
+	return validateArtwork(artwork, new Set((0, _scenography_plugin_wall_data.allEdgeNames)(walls)));
+};
+//#endregion
+//#region src/data/plugin.ts
+/**
+* The data half of the artwork plugin: owns the `artworks` scene key (a
+* collection) and validates each piece — including that a wall-hung piece
+* references a real wall edge. Pure — no three.js.
+*/
+const artworkData = {
+	kind: "artworks",
+	cardinality: "many",
+	validate: (artwork, ctx) => validateArtworkInScene(artwork, ctx)
+};
+//#endregion
+Object.defineProperty(exports, "DEFAULT_ARTWORK_FIELDS", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_ARTWORK_FIELDS;
+	}
+});
+Object.defineProperty(exports, "artworkData", {
+	enumerable: true,
+	get: function() {
+		return artworkData;
+	}
+});
+Object.defineProperty(exports, "validateArtwork", {
+	enumerable: true,
+	get: function() {
+		return validateArtwork;
+	}
+});
+Object.defineProperty(exports, "validateArtworkInScene", {
+	enumerable: true,
+	get: function() {
+		return validateArtworkInScene;
+	}
+});
+
+//# sourceMappingURL=data-WcCPqQ_k.cjs.map

package/dist/data-WcCPqQ_k.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-WcCPqQ_k.cjs","names":["isVec2","isNonNegativeNumber","isIntegerNumber","isString","isPositiveNumber","isFiniteNumber","isObject","isMeasure","isVec3"],"sources":["../src/data/artwork.ts","../src/data/validate.ts","../src/data/plugin.ts"],"sourcesContent":["import type { Measure, SurfaceTexture, Vec2, Vec3 } from \"@scenography/scene\";\n\n/**\n * Where an artwork is placed. Extensible via `type`; today a piece either hangs\n * on a named wall edge or floats freely. Future element types (floor, ceiling…)\n * add new variants here.\n */\nexport type ArtworkLocation =\n  | {\n      type: \"wall\";\n      /** Name of the `NamedEdge` to hang on. */\n      edge: string;\n      /** Position along the edge: a number is units from the edge start, `'50%'` is a fraction. */\n      position: Measure;\n      /**\n       * Vertical placement: a number is an absolute world Y, `'50%'` is a\n       * fraction of the wall height. Omitted defaults to the camera's eye height.\n       */\n      height?: Measure;\n      /**\n       * Which face of the wall the piece shows on, relative to the edge\n       * direction. `'right'` (default) is the right-hand side when walking the\n       * edge from its start vertex to its end vertex.\n       */\n      side?: \"right\" | \"left\";\n    }\n  | {\n      type: \"floating\";\n      /** World position `[x, y, z]`. */\n      point: Vec3;\n      /** Y-axis rotation in radians. Defaults to `0`. */\n      yaw?: number;\n    };\n\n/**\n * A passepartout (mat) sitting between the frame and the image: a flat border\n * that insets the image. Only meaningful when the artwork has a `frame`.\n */\nexport interface Passepartout {\n  /** Mat border width around the image, in world units. Defaults to `6`. */\n  width?: number;\n  /** Mat color (CSS). Defaults to an off-white. */\n  color?: string;\n}\n\n/**\n * A frame around an artwork. By default it's four flat bars rendered with a\n * solid `color` or a `texture` (e.g. wood). For an ornate, sculpted frame, point\n * `model` at an external glTF/GLB instead. A `passepartout` mat can sit between\n * the frame and the image.\n */\nexport interface Frame {\n  /** Border width (how wide the frame face is), in world units. Defaults to `5`. */\n  width?: number;\n  /** How far the frame stands proud of the artwork face, in world units. Defaults to `3`. */\n  depth?: number;\n  /** Frame color (CSS). Defaults to a dark tone. Ignored when `texture` or `model` is set. */\n  color?: string;\n  /** Surface texture (e.g. wood); takes visual precedence over `color`. */\n  texture?: SurfaceTexture;\n  /** External glTF/GLB model for an ornate frame; replaces the generated bars. */\n  model?: string;\n  /** Passepartout mat between the frame and the image. */\n  passepartout?: Passepartout;\n}\n\n/**\n * Commercial status of a piece. Gallery convention: a colored dot signals\n * availability. The dot's color is presentation (decided by the renderer), not\n * data — this is the state it derives from.\n */\nexport type Availability = \"for-sale\" | \"sold\" | \"not-for-sale\";\n\n/**\n * The fields a label/info card can show, identified by name. A `fields` array\n * toggles which are visible; the render order is fixed (it is not the array\n * order): title, then author/year, then technique + dimensions on one line, with\n * availability shown as a corner dot. Shared by the physical label (engine) and\n * the overlay info card.\n */\nexport type ArtworkField = \"title\" | \"author\" | \"year\" | \"technique\" | \"dimensions\" | \"availability\";\n\n/** Default visibility when a label/card doesn't specify its own `fields`. */\nexport const DEFAULT_ARTWORK_FIELDS: readonly ArtworkField[] = [\n  \"title\",\n  \"technique\",\n  \"dimensions\",\n  \"availability\",\n];\n\n/**\n * A physical wall label (cartela) materialized next to the piece. Its presence\n * is the opt-in; the engine renders it from the artwork's own data.\n */\nexport interface ArtworkLabel {\n  /** Where the label sits relative to the piece. Defaults to `'below'`. */\n  side?: \"below\" | \"left\" | \"right\";\n  /** Which fields to show. Defaults to `DEFAULT_ARTWORK_FIELDS`. */\n  fields?: ArtworkField[];\n  /**\n   * Size multiplier over the real physical size (24pt title etc). Defaults to\n   * `1` (true to life), but a real cartela is only a few cm tall — tiny and hard\n   * to read/click at gallery scale — so bump this (e.g. `3`) for legibility.\n   */\n  scale?: number;\n  /**\n   * Fine-tune the placement with an `[x, y]` shift in world units, added on top\n   * of the `side` position (the frame is already cleared). `x` runs along the\n   * wall (right is positive), `y` is vertical (up is positive).\n   */\n  offset?: Vec2;\n}\n\n/** A framed image placed somewhere in the scene. */\nexport interface Artwork {\n  id: string;\n  location: ArtworkLocation;\n  /** Image URL/path to display. */\n  src: string;\n  /** `[width, height]` of the artwork, in world units. */\n  size: Vec2;\n  /**\n   * Box depth (volume) in world units: the piece is a box with the image on the\n   * front and white sides/back. Defaults to `2`.\n   */\n  depth?: number;\n  /** Optional frame around the artwork. */\n  frame?: Frame;\n  title?: string;\n  technique?: string;\n  /** Author / artist name. */\n  author?: string;\n  /** Year the piece was made. */\n  year?: number;\n  /**\n   * Real-world dimensions for display, e.g. `'92 × 73 cm'`. Distinct from `size`,\n   * which is in world units.\n   */\n  dimensions?: string;\n  /** Commercial status; drives the availability dot. */\n  availability?: Availability;\n  /** Long-form caption / catalog entry, shown in the expanded info panel. */\n  description?: string;\n  /**\n   * External URL for the piece (a catalog page, or a marketplace listing when\n   * it's for sale). Surfaced as a link in the expanded info panel.\n   */\n  href?: string;\n  /** When present, a physical wall label is materialized next to the piece. */\n  label?: ArtworkLabel;\n  /**\n   * Max distance (world units) from which the piece can be clicked to open its\n   * info panel. A gate so far-away pieces aren't interactive. Absent = no gate.\n   */\n  infoRadius?: number;\n}\n\ndeclare module \"@scenography/scene\" {\n  interface Scene {\n    /** Framed images placed in the space — provided by `@scenography/plugin-artwork`. */\n    artworks?: Artwork[];\n  }\n}\n","import {\n  eachPropIs,\n  existsProp,\n  fail,\n  isFiniteNumber,\n  isIntegerNumber,\n  isMeasure,\n  isNonNegativeNumber,\n  isObject,\n  isOneOf,\n  isPositiveNumber,\n  isString,\n  isVec2,\n  isVec3,\n  propIs,\n  validate,\n  when,\n  type SceneContext,\n  type ValidationResult,\n} from \"@scenography/scene\";\nimport { allEdgeNames, type Wall } from \"@scenography/plugin-wall/data\";\n\nimport type { Artwork, ArtworkField, Availability } from \"./artwork\";\n\nconst AVAILABILITY: ReadonlySet<Availability> = new Set<Availability>([\n  \"for-sale\",\n  \"sold\",\n  \"not-for-sale\",\n]);\nconst ARTWORK_FIELDS: ReadonlySet<ArtworkField> = new Set<ArtworkField>([\n  \"title\",\n  \"author\",\n  \"year\",\n  \"technique\",\n  \"dimensions\",\n  \"availability\",\n]);\nconst LABEL_SIDES: ReadonlySet<string> = new Set([\"below\", \"left\", \"right\"]);\nconst LOCATION_TYPES: ReadonlySet<string> = new Set([\"wall\", \"floating\"]);\n\nconst locationOfType =\n  (type: string) =>\n  (artwork: Artwork): boolean =>\n    isObject(artwork.location) && artwork.location.type === type;\n\n/**\n * Validate one artwork. `edgeNames` is the set of wall-edge names in the scene,\n * used to check `location.edge` references. Returns every problem found, in\n * order, with paths relative to the artwork (the caller scopes them).\n */\nexport const validateArtwork = (artwork: Artwork, edgeNames: Set<string>): ValidationResult =>\n  validate<Artwork>([\n    existsProp(\"id\", \"Artwork is missing an id.\"),\n    existsProp(\"src\", \"Artwork is missing a src.\"),\n    existsProp(\"size\", \"Artwork is missing a size.\"),\n    propIs(\"size\", isVec2, \"size must be [width, height].\"),\n    propIs(\"depth\", isNonNegativeNumber, \"depth must be a non-negative number.\"),\n    propIs(\"year\", isIntegerNumber, \"year must be an integer.\"),\n    propIs(\"href\", isString, \"href must be a string.\"),\n    propIs(\n      \"availability\",\n      isOneOf(AVAILABILITY),\n      \"availability must be 'for-sale', 'sold' or 'not-for-sale'.\",\n    ),\n    propIs(\"infoRadius\", isPositiveNumber, \"infoRadius must be a positive number.\"),\n    propIs(\"label.side\", isOneOf(LABEL_SIDES), \"side must be 'below', 'left' or 'right'.\"),\n    propIs(\"label.fields\", Array.isArray, \"fields must be an array.\"),\n    eachPropIs(\"label.fields\", isOneOf(ARTWORK_FIELDS), (field) => `unknown field \"${String(field)}\".`),\n    propIs(\"label.scale\", isPositiveNumber, \"scale must be a positive number.\"),\n    propIs(\"label.offset\", isVec2, \"offset must be [x, y].\"),\n    propIs(\"frame.width\", isFiniteNumber, \"width must be a finite number.\"),\n    propIs(\"frame.depth\", isFiniteNumber, \"depth must be a finite number.\"),\n    when(\n      (a: Artwork) => a.frame?.texture !== undefined,\n      existsProp(\"frame.texture.src\", \"frame texture is missing a src.\"),\n    ),\n    propIs(\n      \"frame.passepartout.width\",\n      isFiniteNumber,\n      \"passepartout width must be a finite number.\",\n    ),\n    existsProp(\"location\", \"Artwork is missing a location.\"),\n    propIs(\"location\", isObject, \"location must be an object.\"),\n    when(\n      locationOfType(\"wall\"),\n      existsProp(\"location.edge\"),\n      propIs(\n        \"location.edge\",\n        (edge) => isString(edge) && edgeNames.has(edge),\n        (edge) => `references unknown edge \"${String(edge)}\".`,\n      ),\n      existsProp(\"location.position\"),\n      propIs(\"location.position\", isMeasure, \"position must be a number or a percentage string.\"),\n      propIs(\"location.height\", isMeasure, \"height must be a number or a percentage string.\"),\n    ),\n    when(\n      locationOfType(\"floating\"),\n      existsProp(\"location.point\"),\n      propIs(\"location.point\", isVec3, \"point must be [x, y, z].\"),\n    ),\n    when(\n      (a: Artwork) => isObject(a.location) && !isOneOf(LOCATION_TYPES)(a.location.type),\n      fail(\"location.type\", \"unknown location type.\"),\n    ),\n  ])(artwork);\n\n/**\n * Validate an artwork against its scene: resolves the set of valid wall-edge\n * names from the scene's walls (the wall plugin's data half) so `location.edge`\n * references are checked. Floating pieces don't need any wall.\n */\nexport const validateArtworkInScene = (artwork: Artwork, ctx: SceneContext): ValidationResult => {\n  const walls = (ctx.scene as { walls?: Wall[] }).walls ?? [];\n  return validateArtwork(artwork, new Set(allEdgeNames(walls)));\n};\n","import type { DataPlugin } from \"@scenography/scene\";\n\nimport { validateArtworkInScene } from \"./validate\";\nimport type { Artwork } from \"./artwork\";\n\n/**\n * The data half of the artwork plugin: owns the `artworks` scene key (a\n * collection) and validates each piece — including that a wall-hung piece\n * references a real wall edge. Pure — no three.js.\n */\nexport const artworkData: DataPlugin<Artwork> = {\n  kind: \"artworks\",\n  cardinality: \"many\",\n  validate: (artwork, ctx) => validateArtworkInScene(artwork, ctx),\n};\n"],"mappings":";;;;AAmFA,MAAa,yBAAkD;CAC7D;CACA;CACA;CACA;AACF;;;AChEA,MAAM,eAA0C,IAAI,IAAkB;CACpE;CACA;CACA;AACF,CAAC;AACD,MAAM,iBAA4C,IAAI,IAAkB;CACtE;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;AACD,MAAM,cAAmC,IAAI,IAAI;CAAC;CAAS;CAAQ;AAAO,CAAC;AAC3E,MAAM,iBAAsC,IAAI,IAAI,CAAC,QAAQ,UAAU,CAAC;AAExE,MAAM,kBACH,UACA,aAAA,GAAA,mBAAA,SAAA,CACU,QAAQ,QAAQ,KAAK,QAAQ,SAAS,SAAS;;;;;;AAO5D,MAAa,mBAAmB,SAAkB,eAAA,GAAA,mBAAA,SAAA,CAC9B;oCACL,MAAM,2BAA2B;oCACjC,OAAO,2BAA2B;oCAClC,QAAQ,4BAA4B;gCACxC,QAAQA,mBAAAA,QAAQ,+BAA+B;gCAC/C,SAASC,mBAAAA,qBAAqB,sCAAsC;gCACpE,QAAQC,mBAAAA,iBAAiB,0BAA0B;gCACnD,QAAQC,mBAAAA,UAAU,wBAAwB;gCAE/C,iBAAA,GAAA,mBAAA,QAAA,CACQ,YAAY,GACpB,4DACF;gCACO,cAAcC,mBAAAA,kBAAkB,uCAAuC;gCACvE,eAAA,GAAA,mBAAA,QAAA,CAAsB,WAAW,GAAG,0CAA0C;gCAC9E,gBAAgB,MAAM,SAAS,0BAA0B;oCACrD,iBAAA,GAAA,mBAAA,QAAA,CAAwB,cAAc,IAAI,UAAU,kBAAkB,OAAO,KAAK,EAAE,GAAG;gCAC3F,eAAeA,mBAAAA,kBAAkB,kCAAkC;gCACnE,gBAAgBJ,mBAAAA,QAAQ,wBAAwB;gCAChD,eAAeK,mBAAAA,gBAAgB,gCAAgC;gCAC/D,eAAeA,mBAAAA,gBAAgB,gCAAgC;+BAEnE,MAAe,EAAE,OAAO,YAAY,KAAA,IAAA,GAAA,mBAAA,WAAA,CAC1B,qBAAqB,iCAAiC,CACnE;gCAEE,4BACAA,mBAAAA,gBACA,6CACF;oCACW,YAAY,gCAAgC;gCAChD,YAAYC,mBAAAA,UAAU,6BAA6B;8BAExD,eAAe,MAAM,IAAA,GAAA,mBAAA,WAAA,CACV,eAAe,IAAA,GAAA,mBAAA,OAAA,CAExB,kBACC,UAAA,GAAA,mBAAA,SAAA,CAAkB,IAAI,KAAK,UAAU,IAAI,IAAI,IAC7C,SAAS,4BAA4B,OAAO,IAAI,EAAE,GACrD,IAAA,GAAA,mBAAA,WAAA,CACW,mBAAmB,IAAA,GAAA,mBAAA,OAAA,CACvB,qBAAqBC,mBAAAA,WAAW,mDAAmD,IAAA,GAAA,mBAAA,OAAA,CACnF,mBAAmBA,mBAAAA,WAAW,iDAAiD,CACxF;8BAEE,eAAe,UAAU,IAAA,GAAA,mBAAA,WAAA,CACd,gBAAgB,IAAA,GAAA,mBAAA,OAAA,CACpB,kBAAkBC,mBAAAA,QAAQ,0BAA0B,CAC7D;+BAEG,OAAA,GAAA,mBAAA,SAAA,CAAwB,EAAE,QAAQ,KAAK,EAAA,GAAA,mBAAA,QAAA,CAAS,cAAc,CAAC,CAAC,EAAE,SAAS,IAAI,IAAA,GAAA,mBAAA,KAAA,CAC3E,iBAAiB,wBAAwB,CAChD;AACF,CAAC,CAAC,CAAC,OAAO;;;;;;AAOZ,MAAa,0BAA0B,SAAkB,QAAwC;CAC/F,MAAM,QAAS,IAAI,MAA6B,SAAS,CAAC;CAC1D,OAAO,gBAAgB,SAAS,IAAI,KAAA,GAAA,8BAAA,aAAA,CAAiB,KAAK,CAAC,CAAC;AAC9D;;;;;;;;ACxGA,MAAa,cAAmC;CAC9C,MAAM;CACN,aAAa;CACb,WAAW,SAAS,QAAQ,uBAAuB,SAAS,GAAG;AACjE"}

package/dist/data.cjs

@@ -0,0 +1,6 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_data = require("./data-WcCPqQ_k.cjs");
+exports.DEFAULT_ARTWORK_FIELDS = require_data.DEFAULT_ARTWORK_FIELDS;
+exports.artworkData = require_data.artworkData;
+exports.validateArtwork = require_data.validateArtwork;
+exports.validateArtworkInScene = require_data.validateArtworkInScene;

package/dist/data.d.cts

@@ -0,0 +1,2 @@
+import { a as ArtworkField, c as Availability, d as Passepartout, i as Artwork, l as DEFAULT_ARTWORK_FIELDS, n as validateArtwork, o as ArtworkLabel, r as validateArtworkInScene, s as ArtworkLocation, t as artworkData, u as Frame } from "./index-XUkegdM8.cjs";
+export { type Artwork, type ArtworkField, type ArtworkLabel, type ArtworkLocation, type Availability, DEFAULT_ARTWORK_FIELDS, type Frame, type Passepartout, artworkData, validateArtwork, validateArtworkInScene };

package/dist/data.d.mts

@@ -0,0 +1,2 @@
+import { a as ArtworkField, c as Availability, d as Passepartout, i as Artwork, l as DEFAULT_ARTWORK_FIELDS, n as validateArtwork, o as ArtworkLabel, r as validateArtworkInScene, s as ArtworkLocation, t as artworkData, u as Frame } from "./index-XUkegdM8.mjs";
+export { type Artwork, type ArtworkField, type ArtworkLabel, type ArtworkLocation, type Availability, DEFAULT_ARTWORK_FIELDS, type Frame, type Passepartout, artworkData, validateArtwork, validateArtworkInScene };

package/dist/data.mjs

@@ -0,0 +1,2 @@
+import { i as DEFAULT_ARTWORK_FIELDS, n as validateArtwork, r as validateArtworkInScene, t as artworkData } from "./data-BsI0PbuK.mjs";
+export { DEFAULT_ARTWORK_FIELDS, artworkData, validateArtwork, validateArtworkInScene };

package/dist/index-XUkegdM8.d.cts

@@ -0,0 +1,170 @@
+import { DataPlugin, Measure, SceneContext, SurfaceTexture, ValidationResult, Vec2, Vec3 } from "@scenography/scene";
+
+//#region src/data/artwork.d.ts
+/**
+ * Where an artwork is placed. Extensible via `type`; today a piece either hangs
+ * on a named wall edge or floats freely. Future element types (floor, ceiling…)
+ * add new variants here.
+ */
+type ArtworkLocation = {
+  type: "wall"; /** Name of the `NamedEdge` to hang on. */
+  edge: string; /** Position along the edge: a number is units from the edge start, `'50%'` is a fraction. */
+  position: Measure;
+  /**
+   * Vertical placement: a number is an absolute world Y, `'50%'` is a
+   * fraction of the wall height. Omitted defaults to the camera's eye height.
+   */
+  height?: Measure;
+  /**
+   * Which face of the wall the piece shows on, relative to the edge
+   * direction. `'right'` (default) is the right-hand side when walking the
+   * edge from its start vertex to its end vertex.
+   */
+  side?: "right" | "left";
+} | {
+  type: "floating"; /** World position `[x, y, z]`. */
+  point: Vec3; /** Y-axis rotation in radians. Defaults to `0`. */
+  yaw?: number;
+};
+/**
+ * A passepartout (mat) sitting between the frame and the image: a flat border
+ * that insets the image. Only meaningful when the artwork has a `frame`.
+ */
+interface Passepartout {
+  /** Mat border width around the image, in world units. Defaults to `6`. */
+  width?: number;
+  /** Mat color (CSS). Defaults to an off-white. */
+  color?: string;
+}
+/**
+ * A frame around an artwork. By default it's four flat bars rendered with a
+ * solid `color` or a `texture` (e.g. wood). For an ornate, sculpted frame, point
+ * `model` at an external glTF/GLB instead. A `passepartout` mat can sit between
+ * the frame and the image.
+ */
+interface Frame {
+  /** Border width (how wide the frame face is), in world units. Defaults to `5`. */
+  width?: number;
+  /** How far the frame stands proud of the artwork face, in world units. Defaults to `3`. */
+  depth?: number;
+  /** Frame color (CSS). Defaults to a dark tone. Ignored when `texture` or `model` is set. */
+  color?: string;
+  /** Surface texture (e.g. wood); takes visual precedence over `color`. */
+  texture?: SurfaceTexture;
+  /** External glTF/GLB model for an ornate frame; replaces the generated bars. */
+  model?: string;
+  /** Passepartout mat between the frame and the image. */
+  passepartout?: Passepartout;
+}
+/**
+ * Commercial status of a piece. Gallery convention: a colored dot signals
+ * availability. The dot's color is presentation (decided by the renderer), not
+ * data — this is the state it derives from.
+ */
+type Availability = "for-sale" | "sold" | "not-for-sale";
+/**
+ * The fields a label/info card can show, identified by name. A `fields` array
+ * toggles which are visible; the render order is fixed (it is not the array
+ * order): title, then author/year, then technique + dimensions on one line, with
+ * availability shown as a corner dot. Shared by the physical label (engine) and
+ * the overlay info card.
+ */
+type ArtworkField = "title" | "author" | "year" | "technique" | "dimensions" | "availability";
+/** Default visibility when a label/card doesn't specify its own `fields`. */
+declare const DEFAULT_ARTWORK_FIELDS: readonly ArtworkField[];
+/**
+ * A physical wall label (cartela) materialized next to the piece. Its presence
+ * is the opt-in; the engine renders it from the artwork's own data.
+ */
+interface ArtworkLabel {
+  /** Where the label sits relative to the piece. Defaults to `'below'`. */
+  side?: "below" | "left" | "right";
+  /** Which fields to show. Defaults to `DEFAULT_ARTWORK_FIELDS`. */
+  fields?: ArtworkField[];
+  /**
+   * Size multiplier over the real physical size (24pt title etc). Defaults to
+   * `1` (true to life), but a real cartela is only a few cm tall — tiny and hard
+   * to read/click at gallery scale — so bump this (e.g. `3`) for legibility.
+   */
+  scale?: number;
+  /**
+   * Fine-tune the placement with an `[x, y]` shift in world units, added on top
+   * of the `side` position (the frame is already cleared). `x` runs along the
+   * wall (right is positive), `y` is vertical (up is positive).
+   */
+  offset?: Vec2;
+}
+/** A framed image placed somewhere in the scene. */
+interface Artwork {
+  id: string;
+  location: ArtworkLocation;
+  /** Image URL/path to display. */
+  src: string;
+  /** `[width, height]` of the artwork, in world units. */
+  size: Vec2;
+  /**
+   * Box depth (volume) in world units: the piece is a box with the image on the
+   * front and white sides/back. Defaults to `2`.
+   */
+  depth?: number;
+  /** Optional frame around the artwork. */
+  frame?: Frame;
+  title?: string;
+  technique?: string;
+  /** Author / artist name. */
+  author?: string;
+  /** Year the piece was made. */
+  year?: number;
+  /**
+   * Real-world dimensions for display, e.g. `'92 × 73 cm'`. Distinct from `size`,
+   * which is in world units.
+   */
+  dimensions?: string;
+  /** Commercial status; drives the availability dot. */
+  availability?: Availability;
+  /** Long-form caption / catalog entry, shown in the expanded info panel. */
+  description?: string;
+  /**
+   * External URL for the piece (a catalog page, or a marketplace listing when
+   * it's for sale). Surfaced as a link in the expanded info panel.
+   */
+  href?: string;
+  /** When present, a physical wall label is materialized next to the piece. */
+  label?: ArtworkLabel;
+  /**
+   * Max distance (world units) from which the piece can be clicked to open its
+   * info panel. A gate so far-away pieces aren't interactive. Absent = no gate.
+   */
+  infoRadius?: number;
+}
+declare module "@scenography/scene" {
+  interface Scene {
+    /** Framed images placed in the space — provided by `@scenography/plugin-artwork`. */
+    artworks?: Artwork[];
+  }
+}
+//#endregion
+//#region src/data/validate.d.ts
+/**
+ * Validate one artwork. `edgeNames` is the set of wall-edge names in the scene,
+ * used to check `location.edge` references. Returns every problem found, in
+ * order, with paths relative to the artwork (the caller scopes them).
+ */
+declare const validateArtwork: (artwork: Artwork, edgeNames: Set<string>) => ValidationResult;
+/**
+ * Validate an artwork against its scene: resolves the set of valid wall-edge
+ * names from the scene's walls (the wall plugin's data half) so `location.edge`
+ * references are checked. Floating pieces don't need any wall.
+ */
+declare const validateArtworkInScene: (artwork: Artwork, ctx: SceneContext) => ValidationResult;
+//#endregion
+//#region src/data/plugin.d.ts
+/**
+ * The data half of the artwork plugin: owns the `artworks` scene key (a
+ * collection) and validates each piece — including that a wall-hung piece
+ * references a real wall edge. Pure — no three.js.
+ */
+declare const artworkData: DataPlugin<Artwork>;
+//#endregion
+export { ArtworkField as a, Availability as c, Passepartout as d, Artwork as i, DEFAULT_ARTWORK_FIELDS as l, validateArtwork as n, ArtworkLabel as o, validateArtworkInScene as r, ArtworkLocation as s, artworkData as t, Frame as u };
+//# sourceMappingURL=index-XUkegdM8.d.cts.map

package/dist/index-XUkegdM8.d.mts

@@ -0,0 +1,170 @@
+import { DataPlugin, Measure, SceneContext, SurfaceTexture, ValidationResult, Vec2, Vec3 } from "@scenography/scene";
+
+//#region src/data/artwork.d.ts
+/**
+ * Where an artwork is placed. Extensible via `type`; today a piece either hangs
+ * on a named wall edge or floats freely. Future element types (floor, ceiling…)
+ * add new variants here.
+ */
+type ArtworkLocation = {
+  type: "wall"; /** Name of the `NamedEdge` to hang on. */
+  edge: string; /** Position along the edge: a number is units from the edge start, `'50%'` is a fraction. */
+  position: Measure;
+  /**
+   * Vertical placement: a number is an absolute world Y, `'50%'` is a
+   * fraction of the wall height. Omitted defaults to the camera's eye height.
+   */
+  height?: Measure;
+  /**
+   * Which face of the wall the piece shows on, relative to the edge
+   * direction. `'right'` (default) is the right-hand side when walking the
+   * edge from its start vertex to its end vertex.
+   */
+  side?: "right" | "left";
+} | {
+  type: "floating"; /** World position `[x, y, z]`. */
+  point: Vec3; /** Y-axis rotation in radians. Defaults to `0`. */
+  yaw?: number;
+};
+/**
+ * A passepartout (mat) sitting between the frame and the image: a flat border
+ * that insets the image. Only meaningful when the artwork has a `frame`.
+ */
+interface Passepartout {
+  /** Mat border width around the image, in world units. Defaults to `6`. */
+  width?: number;
+  /** Mat color (CSS). Defaults to an off-white. */
+  color?: string;
+}
+/**
+ * A frame around an artwork. By default it's four flat bars rendered with a
+ * solid `color` or a `texture` (e.g. wood). For an ornate, sculpted frame, point
+ * `model` at an external glTF/GLB instead. A `passepartout` mat can sit between
+ * the frame and the image.
+ */
+interface Frame {
+  /** Border width (how wide the frame face is), in world units. Defaults to `5`. */
+  width?: number;
+  /** How far the frame stands proud of the artwork face, in world units. Defaults to `3`. */
+  depth?: number;
+  /** Frame color (CSS). Defaults to a dark tone. Ignored when `texture` or `model` is set. */
+  color?: string;
+  /** Surface texture (e.g. wood); takes visual precedence over `color`. */
+  texture?: SurfaceTexture;
+  /** External glTF/GLB model for an ornate frame; replaces the generated bars. */
+  model?: string;
+  /** Passepartout mat between the frame and the image. */
+  passepartout?: Passepartout;
+}
+/**
+ * Commercial status of a piece. Gallery convention: a colored dot signals
+ * availability. The dot's color is presentation (decided by the renderer), not
+ * data — this is the state it derives from.
+ */
+type Availability = "for-sale" | "sold" | "not-for-sale";
+/**
+ * The fields a label/info card can show, identified by name. A `fields` array
+ * toggles which are visible; the render order is fixed (it is not the array
+ * order): title, then author/year, then technique + dimensions on one line, with
+ * availability shown as a corner dot. Shared by the physical label (engine) and
+ * the overlay info card.
+ */
+type ArtworkField = "title" | "author" | "year" | "technique" | "dimensions" | "availability";
+/** Default visibility when a label/card doesn't specify its own `fields`. */
+declare const DEFAULT_ARTWORK_FIELDS: readonly ArtworkField[];
+/**
+ * A physical wall label (cartela) materialized next to the piece. Its presence
+ * is the opt-in; the engine renders it from the artwork's own data.
+ */
+interface ArtworkLabel {
+  /** Where the label sits relative to the piece. Defaults to `'below'`. */
+  side?: "below" | "left" | "right";
+  /** Which fields to show. Defaults to `DEFAULT_ARTWORK_FIELDS`. */
+  fields?: ArtworkField[];
+  /**
+   * Size multiplier over the real physical size (24pt title etc). Defaults to
+   * `1` (true to life), but a real cartela is only a few cm tall — tiny and hard
+   * to read/click at gallery scale — so bump this (e.g. `3`) for legibility.
+   */
+  scale?: number;
+  /**
+   * Fine-tune the placement with an `[x, y]` shift in world units, added on top
+   * of the `side` position (the frame is already cleared). `x` runs along the
+   * wall (right is positive), `y` is vertical (up is positive).
+   */
+  offset?: Vec2;
+}
+/** A framed image placed somewhere in the scene. */
+interface Artwork {
+  id: string;
+  location: ArtworkLocation;
+  /** Image URL/path to display. */
+  src: string;
+  /** `[width, height]` of the artwork, in world units. */
+  size: Vec2;
+  /**
+   * Box depth (volume) in world units: the piece is a box with the image on the
+   * front and white sides/back. Defaults to `2`.
+   */
+  depth?: number;
+  /** Optional frame around the artwork. */
+  frame?: Frame;
+  title?: string;
+  technique?: string;
+  /** Author / artist name. */
+  author?: string;
+  /** Year the piece was made. */
+  year?: number;
+  /**
+   * Real-world dimensions for display, e.g. `'92 × 73 cm'`. Distinct from `size`,
+   * which is in world units.
+   */
+  dimensions?: string;
+  /** Commercial status; drives the availability dot. */
+  availability?: Availability;
+  /** Long-form caption / catalog entry, shown in the expanded info panel. */
+  description?: string;
+  /**
+   * External URL for the piece (a catalog page, or a marketplace listing when
+   * it's for sale). Surfaced as a link in the expanded info panel.
+   */
+  href?: string;
+  /** When present, a physical wall label is materialized next to the piece. */
+  label?: ArtworkLabel;
+  /**
+   * Max distance (world units) from which the piece can be clicked to open its
+   * info panel. A gate so far-away pieces aren't interactive. Absent = no gate.
+   */
+  infoRadius?: number;
+}
+declare module "@scenography/scene" {
+  interface Scene {
+    /** Framed images placed in the space — provided by `@scenography/plugin-artwork`. */
+    artworks?: Artwork[];
+  }
+}
+//#endregion
+//#region src/data/validate.d.ts
+/**
+ * Validate one artwork. `edgeNames` is the set of wall-edge names in the scene,
+ * used to check `location.edge` references. Returns every problem found, in
+ * order, with paths relative to the artwork (the caller scopes them).
+ */
+declare const validateArtwork: (artwork: Artwork, edgeNames: Set<string>) => ValidationResult;
+/**
+ * Validate an artwork against its scene: resolves the set of valid wall-edge
+ * names from the scene's walls (the wall plugin's data half) so `location.edge`
+ * references are checked. Floating pieces don't need any wall.
+ */
+declare const validateArtworkInScene: (artwork: Artwork, ctx: SceneContext) => ValidationResult;
+//#endregion
+//#region src/data/plugin.d.ts
+/**
+ * The data half of the artwork plugin: owns the `artworks` scene key (a
+ * collection) and validates each piece — including that a wall-hung piece
+ * references a real wall edge. Pure — no three.js.
+ */
+declare const artworkData: DataPlugin<Artwork>;
+//#endregion
+export { ArtworkField as a, Availability as c, Passepartout as d, Artwork as i, DEFAULT_ARTWORK_FIELDS as l, validateArtwork as n, ArtworkLabel as o, validateArtworkInScene as r, ArtworkLocation as s, artworkData as t, Frame as u };
+//# sourceMappingURL=index-XUkegdM8.d.mts.map