@hoardodile/sdk-types 0.0.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Wooloo <ayan0312000@gmail.com>
+
+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,59 @@
+# @hoardodile/sdk-types
+
+The plugin manifest contract and shared message/danmaku/anchor shapes —
+the single source of truth for wire types consumed by every SDK package,
+the host, and the app. Nothing here touches the DOM or node.
+
+## Install
+
+```bash
+pnpm add @hoardodile/sdk-types
+```
+
+## What's in it
+
+The root entry is **zod-free** — plugin bundles that import it never
+pull zod. Runtime validators live behind the
+`@hoardodile/sdk-types/schema` subpath, used only by the host, the
+server, and tooling.
+
+- **`PluginSchema`** — the per-plugin schema interface: declare `file`,
+  `sourceMeta`, `searchMeta`, `anchor` once and both `definePlugin`
+  (`@hoardodile/sdk-server`) and the web API (`@hoardodile/sdk-web` /
+  `@hoardodile/sdk-react`) are typed from it
+- **Plugin definition** — `PluginDefinition`/`ResourceAPI`/`definePlugin`/
+  fixtures/`HOOK_NAMES`, re-exported by `@hoardodile/sdk-server`
+- **Wire shapes** — `Message`, `Danmaku`, `ResAnchor`, `AnchorData`,
+  `DanmakuMode`, `DanmakuListFilter`, `FileStats`, `SearchMeta`,
+  `SerializedFileList`, `ReadFileRange`
+- **Template vocabulary** — the corner-template and anchor-chip
+  directives the host's template engine renders
+- **`@hoardodile/sdk-types/schema`** — the zod layer: `pluginManifest`
+  (validated everywhere via its parse: server install, build CLI,
+  workbench), `pluginManifestId`, `anchorData`
+- **Constants** (subpath-only, no root export):
+  - `@hoardodile/sdk-types/media-exts` — canonical media extension
+    sets: `IMAGE_EXTS`, `VIDEO_EXTS`, `AUDIO_EXTS`, extension ↔ MIME /
+    media-kind lookups
+  - `@hoardodile/sdk-types/plugin` — plugin runtime limits: read cap
+    (`PLUGIN_READ_FILE_MAX_BYTES`), probe/stat fan-out bounds, animation
+    scan batch
+  - `@hoardodile/sdk-types/resource` — resource caps: `SEARCH_META_VERSION`,
+    preview eligibility caps
+  - `@hoardodile/sdk-types/image-variant` — derived-image variant
+    contract: spec types, query parsing/encoding, canonical cache
+    identity
+  - `@hoardodile/sdk-types/template` — the host cover/message template
+    grammar (tokeniser, parser — shared with the web renderer and the
+    CLI's build-time lint)
+  - `@hoardodile/sdk-types/text-limits` — plugin input limits:
+    `MAX_DANMAKU_TEXT_LENGTH`, `MAX_COMMENT_BODY_LENGTH`
+
+## When to import it
+
+Usually only for types (`PluginSchema`, `PluginManifest`).
+`@hoardodile/sdk-server` re-exports the plugin definition and the
+message/danmaku shapes; `@hoardodile/sdk-web` re-exports the wire types
+its consumers need — you rarely import this package directly in plugin
+code. Reach for `/schema` only when you need a runtime validator (app
+code, tooling).

package/dist/image-variant.d.ts

@@ -0,0 +1,90 @@
+declare const IMAGE_VARIANT_FORMATS: readonly ["avif", "webp"];
+type ImageVariantFormat = (typeof IMAGE_VARIANT_FORMATS)[number];
+/**
+ * How the source image is fitted into the variant:
+ * - `inside` — downscaled (never upscaled) to fit within `maxArea`;
+ * - `exact` — transcode only: output pixels are exactly the source
+ *   dimensions (needed when downstream code maps coordinates onto the
+ *   texture, e.g. Live2D models).
+ */
+declare const IMAGE_VARIANT_FITS: readonly ["inside", "exact"];
+type ImageVariantFit = (typeof IMAGE_VARIANT_FITS)[number];
+/** Upper bound for the `area` query param (bounded cache-key space). */
+declare const IMAGE_VARIANT_MAX_AREA = 1000000000;
+/** Encode-quality range for the `q` query param. */
+declare const IMAGE_VARIANT_MIN_QUALITY = 1;
+declare const IMAGE_VARIANT_MAX_QUALITY = 100;
+/**
+ * Client-declared variant request. Every field is optional; omitted
+ * fields fall back to the defaults (`format` avif, `fit` inside,
+ * `maxArea` {@link RESOURCE_PREVIEW_MAX_AREA}, per-format quality).
+ * `maxArea` only has an effect when `fit` is `inside`; it is carried
+ * through (and cached under) regardless so URL identity stays stable.
+ */
+type ImageVariantSpec = {
+    readonly format?: ImageVariantFormat;
+    readonly fit?: ImageVariantFit;
+    readonly maxArea?: number;
+    readonly quality?: number;
+};
+/**
+ * A fully resolved variant: every field concrete, including the
+ * per-format encode qualities the pipeline consumes. This is the render
+ * boundary shape and the input to {@link imageVariantCanonical}.
+ */
+type ResolvedImageVariant = {
+    readonly format: ImageVariantFormat;
+    readonly fit: ImageVariantFit;
+    readonly maxArea: number;
+    readonly webpQuality: number;
+    readonly avifQuality: number;
+};
+/** Query parameters accepted by the resource file route. */
+type ImageVariantQuery = {
+    readonly size?: string;
+    readonly fmt?: string;
+    readonly fit?: string;
+    readonly area?: string | number;
+    readonly q?: string | number;
+};
+type ImageVariantParseResult = {
+    readonly kind: "none";
+} | {
+    readonly kind: "variant";
+    readonly spec: ImageVariantSpec;
+} | {
+    readonly kind: "invalid";
+    readonly reason: string;
+};
+declare function isImageVariantFormat(value: string): value is ImageVariantFormat;
+declare function isImageVariantFit(value: string): value is ImageVariantFit;
+/**
+ * Interpret the file route's query. A variant is requested when
+ * `size=preview` (the compatibility alias) or any variant parameter is
+ * present; otherwise the route serves the original bytes.
+ * Returns `invalid` for out-of-range or malformed values.
+ */
+declare function parseImageVariantQuery(query: ImageVariantQuery): ImageVariantParseResult;
+/**
+ * Fill the request defaults and clamp out-of-range values. `quality` is
+ * the single client knob; it maps onto both per-format pipeline
+ * qualities, which default to the caller's constants when omitted.
+ */
+declare function normalizeImageVariantSpec(spec: ImageVariantSpec, qualityDefaults: {
+    readonly avifQuality: number;
+    readonly webpQuality: number;
+}): ResolvedImageVariant;
+/**
+ * Stable string identity of a resolved variant — the cache key input.
+ * Two requests produce the same identity iff they render identically.
+ */
+declare function imageVariantCanonical(variant: ResolvedImageVariant): string;
+/**
+ * Encode a variant request as the file route's query string. Always
+ * carries `size=preview` so an older server that does not know the
+ * variant parameters still degrades to its default preview instead of
+ * serving the original bytes.
+ */
+declare function imageVariantQuery(spec: ImageVariantSpec): string;
+
+export { IMAGE_VARIANT_FITS, IMAGE_VARIANT_FORMATS, IMAGE_VARIANT_MAX_AREA, IMAGE_VARIANT_MAX_QUALITY, IMAGE_VARIANT_MIN_QUALITY, type ImageVariantFit, type ImageVariantFormat, type ImageVariantParseResult, type ImageVariantQuery, type ImageVariantSpec, type ResolvedImageVariant, imageVariantCanonical, imageVariantQuery, isImageVariantFit, isImageVariantFormat, normalizeImageVariantSpec, parseImageVariantQuery };

package/dist/image-variant.js

@@ -0,0 +1,115 @@
+// src/resource.ts
+var RESOURCE_PREVIEW_MAX_AREA = 4e6;
+
+// src/image-variant.ts
+var IMAGE_VARIANT_FORMATS = ["avif", "webp"];
+var IMAGE_VARIANT_FITS = ["inside", "exact"];
+var IMAGE_VARIANT_MAX_AREA = 1e9;
+var IMAGE_VARIANT_MIN_QUALITY = 1;
+var IMAGE_VARIANT_MAX_QUALITY = 100;
+function isImageVariantFormat(value) {
+  return IMAGE_VARIANT_FORMATS.some((format) => format === value);
+}
+function isImageVariantFit(value) {
+  return IMAGE_VARIANT_FITS.some((fit) => fit === value);
+}
+function parseImageVariantQuery(query) {
+  const requested = query.size === "preview" || query.fmt !== void 0 || query.fit !== void 0 || query.area !== void 0 || query.q !== void 0;
+  if (!requested) return { kind: "none" };
+  let format;
+  let fit;
+  let maxArea;
+  let quality;
+  if (query.fmt !== void 0) {
+    if (!isImageVariantFormat(query.fmt)) {
+      return invalidFormat(query.fmt);
+    }
+    format = query.fmt;
+  }
+  if (query.fit !== void 0) {
+    if (!isImageVariantFit(query.fit)) {
+      return invalidFit(query.fit);
+    }
+    fit = query.fit;
+  }
+  if (query.area !== void 0) {
+    const area = parseVariantInteger(query.area, IMAGE_VARIANT_MAX_AREA);
+    if (area === void 0) return invalidArea(query.area);
+    maxArea = area;
+  }
+  if (query.q !== void 0) {
+    const q = parseVariantInteger(query.q, IMAGE_VARIANT_MAX_QUALITY);
+    if (q === void 0) return invalidQuality(query.q);
+    quality = q;
+  }
+  return { kind: "variant", spec: { format, fit, maxArea, quality } };
+}
+function invalidFormat(value) {
+  return {
+    kind: "invalid",
+    reason: `invalid format "${value}" (expected ${IMAGE_VARIANT_FORMATS.join(", ")})`
+  };
+}
+function invalidFit(value) {
+  return {
+    kind: "invalid",
+    reason: `invalid fit "${value}" (expected ${IMAGE_VARIANT_FITS.join(", ")})`
+  };
+}
+function invalidArea(value) {
+  return {
+    kind: "invalid",
+    reason: `area must be an integer between 1 and ${IMAGE_VARIANT_MAX_AREA} (got "${String(value)}")`
+  };
+}
+function invalidQuality(value) {
+  return {
+    kind: "invalid",
+    reason: `quality must be an integer between ${IMAGE_VARIANT_MIN_QUALITY} and ${IMAGE_VARIANT_MAX_QUALITY} (got "${String(value)}")`
+  };
+}
+function parseVariantInteger(value, max) {
+  const num = typeof value === "number" ? value : Number(value);
+  if (!Number.isInteger(num)) return void 0;
+  if (num < 1 || num > max) return void 0;
+  return num;
+}
+function normalizeImageVariantSpec(spec, qualityDefaults) {
+  return {
+    format: spec.format ?? "avif",
+    fit: spec.fit ?? "inside",
+    maxArea: clampArea(spec.maxArea ?? RESOURCE_PREVIEW_MAX_AREA),
+    avifQuality: clampQuality(spec.quality ?? qualityDefaults.avifQuality),
+    webpQuality: clampQuality(spec.quality ?? qualityDefaults.webpQuality)
+  };
+}
+function clampArea(value) {
+  return Math.min(Math.max(1, Math.round(value)), IMAGE_VARIANT_MAX_AREA);
+}
+function clampQuality(value) {
+  return Math.min(
+    Math.max(IMAGE_VARIANT_MIN_QUALITY, Math.round(value)),
+    IMAGE_VARIANT_MAX_QUALITY
+  );
+}
+function imageVariantCanonical(variant) {
+  return [
+    variant.format,
+    variant.fit,
+    variant.maxArea,
+    variant.webpQuality,
+    variant.avifQuality
+  ].join(":");
+}
+function imageVariantQuery(spec) {
+  const params = ["size=preview"];
+  if (spec.format !== void 0) params.push(`fmt=${spec.format}`);
+  if (spec.fit !== void 0) params.push(`fit=${spec.fit}`);
+  if (spec.maxArea !== void 0) params.push(`area=${spec.maxArea}`);
+  if (spec.quality !== void 0) params.push(`q=${spec.quality}`);
+  return params.join("&");
+}
+
+export { IMAGE_VARIANT_FITS, IMAGE_VARIANT_FORMATS, IMAGE_VARIANT_MAX_AREA, IMAGE_VARIANT_MAX_QUALITY, IMAGE_VARIANT_MIN_QUALITY, imageVariantCanonical, imageVariantQuery, isImageVariantFit, isImageVariantFormat, normalizeImageVariantSpec, parseImageVariantQuery };
+//# sourceMappingURL=image-variant.js.map
+//# sourceMappingURL=image-variant.js.map

package/dist/image-variant.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resource.ts","../src/image-variant.ts"],"names":[],"mappings":"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","file":"image-variant.js","sourcesContent":["/**\n * Plugin-facing resource caps. The preview policy (`exceedsPreviewThresholds`,\n * which consumes the two caps below) lives with its caller in\n * `@hoardodile/sdk-server/helpers`; the cover cap below is consumed by\n * the app's thumb pipeline, the CLI's workbench renders and the media\n * helpers in `@hoardodile/host`. Character image-area caps stay\n * app-internal in `@hoardodile/shared`.\n */\n\n/**\n * Schema version stamped onto every `SearchMeta` payload. Plugins\n * that build search-meta MUST emit this exact value so the host can\n * detect format drift across plugin upgrades.\n */\nexport const SEARCH_META_VERSION = 1\n\n/** Max pixel area for resource covers; larger images are scaled down. */\nexport const RESOURCE_COVER_MAX_AREA = 300_000\n\n/** Max pixel area for preview variants served to resource previews. */\nexport const RESOURCE_PREVIEW_MAX_AREA = 4_000_000\n\n/**\n * Byte-size threshold for preview eligibility. An image whose\n * area is at or below the cap may still qualify for preview when\n * its byte size exceeds this value.\n */\nexport const RESOURCE_PREVIEW_SIZE_THRESHOLD = 1_000_000\n","/**\n * Image variant contract: how a plugin asks the host to derive an image\n * from a resource file, and how that request travels on the wire.\n *\n * One {@link ImageVariantSpec} has three projections, all derived from\n * this module:\n *\n * - the URL query (`imageVariantQuery`) the iframe client emits,\n * - the resolved render spec (`normalizeImageVariantSpec`) the\n *   pipelines execute,\n * - the canonical cache identity (`imageVariantCanonical`) that keys\n *   the on-disk caches.\n *\n * The per-format encode qualities are pipeline constants, not part of\n * the wire contract — callers fill them in at the render boundary, so\n * this module stays dependency-free and browser-safe.\n */\nimport { RESOURCE_PREVIEW_MAX_AREA } from \"./resource.ts\"\n\nexport const IMAGE_VARIANT_FORMATS = [\"avif\", \"webp\"] as const\nexport type ImageVariantFormat = (typeof IMAGE_VARIANT_FORMATS)[number]\n\n/**\n * How the source image is fitted into the variant:\n * - `inside` — downscaled (never upscaled) to fit within `maxArea`;\n * - `exact` — transcode only: output pixels are exactly the source\n *   dimensions (needed when downstream code maps coordinates onto the\n *   texture, e.g. Live2D models).\n */\nexport const IMAGE_VARIANT_FITS = [\"inside\", \"exact\"] as const\nexport type ImageVariantFit = (typeof IMAGE_VARIANT_FITS)[number]\n\n/** Upper bound for the `area` query param (bounded cache-key space). */\nexport const IMAGE_VARIANT_MAX_AREA = 1_000_000_000\n\n/** Encode-quality range for the `q` query param. */\nexport const IMAGE_VARIANT_MIN_QUALITY = 1\nexport const IMAGE_VARIANT_MAX_QUALITY = 100\n\n/**\n * Client-declared variant request. Every field is optional; omitted\n * fields fall back to the defaults (`format` avif, `fit` inside,\n * `maxArea` {@link RESOURCE_PREVIEW_MAX_AREA}, per-format quality).\n * `maxArea` only has an effect when `fit` is `inside`; it is carried\n * through (and cached under) regardless so URL identity stays stable.\n */\nexport type ImageVariantSpec = {\n\treadonly format?: ImageVariantFormat\n\treadonly fit?: ImageVariantFit\n\treadonly maxArea?: number\n\treadonly quality?: number\n}\n\n/**\n * A fully resolved variant: every field concrete, including the\n * per-format encode qualities the pipeline consumes. This is the render\n * boundary shape and the input to {@link imageVariantCanonical}.\n */\nexport type ResolvedImageVariant = {\n\treadonly format: ImageVariantFormat\n\treadonly fit: ImageVariantFit\n\treadonly maxArea: number\n\treadonly webpQuality: number\n\treadonly avifQuality: number\n}\n\n/** Query parameters accepted by the resource file route. */\nexport type ImageVariantQuery = {\n\treadonly size?: string\n\treadonly fmt?: string\n\treadonly fit?: string\n\treadonly area?: string | number\n\treadonly q?: string | number\n}\n\nexport type ImageVariantParseResult =\n\t| { readonly kind: \"none\" }\n\t| { readonly kind: \"variant\"; readonly spec: ImageVariantSpec }\n\t| { readonly kind: \"invalid\"; readonly reason: string }\n\nexport function isImageVariantFormat(\n\tvalue: string,\n): value is ImageVariantFormat {\n\treturn IMAGE_VARIANT_FORMATS.some((format) => format === value)\n}\n\nexport function isImageVariantFit(value: string): value is ImageVariantFit {\n\treturn IMAGE_VARIANT_FITS.some((fit) => fit === value)\n}\n\n/**\n * Interpret the file route's query. A variant is requested when\n * `size=preview` (the compatibility alias) or any variant parameter is\n * present; otherwise the route serves the original bytes.\n * Returns `invalid` for out-of-range or malformed values.\n */\nexport function parseImageVariantQuery(\n\tquery: ImageVariantQuery,\n): ImageVariantParseResult {\n\tconst requested =\n\t\tquery.size === \"preview\" ||\n\t\tquery.fmt !== undefined ||\n\t\tquery.fit !== undefined ||\n\t\tquery.area !== undefined ||\n\t\tquery.q !== undefined\n\tif (!requested) return { kind: \"none\" }\n\n\tlet format: ImageVariantFormat | undefined\n\tlet fit: ImageVariantFit | undefined\n\tlet maxArea: number | undefined\n\tlet quality: number | undefined\n\tif (query.fmt !== undefined) {\n\t\tif (!isImageVariantFormat(query.fmt)) {\n\t\t\treturn invalidFormat(query.fmt)\n\t\t}\n\t\tformat = query.fmt\n\t}\n\tif (query.fit !== undefined) {\n\t\tif (!isImageVariantFit(query.fit)) {\n\t\t\treturn invalidFit(query.fit)\n\t\t}\n\t\tfit = query.fit\n\t}\n\tif (query.area !== undefined) {\n\t\tconst area = parseVariantInteger(query.area, IMAGE_VARIANT_MAX_AREA)\n\t\tif (area === undefined) return invalidArea(query.area)\n\t\tmaxArea = area\n\t}\n\tif (query.q !== undefined) {\n\t\tconst q = parseVariantInteger(query.q, IMAGE_VARIANT_MAX_QUALITY)\n\t\tif (q === undefined) return invalidQuality(query.q)\n\t\tquality = q\n\t}\n\treturn { kind: \"variant\", spec: { format, fit, maxArea, quality } }\n}\n\nfunction invalidFormat(value: string): ImageVariantParseResult {\n\treturn {\n\t\tkind: \"invalid\",\n\t\treason: `invalid format \"${value}\" (expected ${IMAGE_VARIANT_FORMATS.join(\", \")})`,\n\t}\n}\n\nfunction invalidFit(value: string): ImageVariantParseResult {\n\treturn {\n\t\tkind: \"invalid\",\n\t\treason: `invalid fit \"${value}\" (expected ${IMAGE_VARIANT_FITS.join(\", \")})`,\n\t}\n}\n\nfunction invalidArea(value: unknown): ImageVariantParseResult {\n\treturn {\n\t\tkind: \"invalid\",\n\t\treason: `area must be an integer between 1 and ${IMAGE_VARIANT_MAX_AREA} (got \"${String(value)}\")`,\n\t}\n}\n\nfunction invalidQuality(value: unknown): ImageVariantParseResult {\n\treturn {\n\t\tkind: \"invalid\",\n\t\treason: `quality must be an integer between ${IMAGE_VARIANT_MIN_QUALITY} and ${IMAGE_VARIANT_MAX_QUALITY} (got \"${String(value)}\")`,\n\t}\n}\n\nfunction parseVariantInteger(\n\tvalue: string | number,\n\tmax: number,\n): number | undefined {\n\tconst num = typeof value === \"number\" ? value : Number(value)\n\tif (!Number.isInteger(num)) return undefined\n\tif (num < 1 || num > max) return undefined\n\treturn num\n}\n\n/**\n * Fill the request defaults and clamp out-of-range values. `quality` is\n * the single client knob; it maps onto both per-format pipeline\n * qualities, which default to the caller's constants when omitted.\n */\nexport function normalizeImageVariantSpec(\n\tspec: ImageVariantSpec,\n\tqualityDefaults: {\n\t\treadonly avifQuality: number\n\t\treadonly webpQuality: number\n\t},\n): ResolvedImageVariant {\n\treturn {\n\t\tformat: spec.format ?? \"avif\",\n\t\tfit: spec.fit ?? \"inside\",\n\t\tmaxArea: clampArea(spec.maxArea ?? RESOURCE_PREVIEW_MAX_AREA),\n\t\tavifQuality: clampQuality(spec.quality ?? qualityDefaults.avifQuality),\n\t\twebpQuality: clampQuality(spec.quality ?? qualityDefaults.webpQuality),\n\t}\n}\n\nfunction clampArea(value: number): number {\n\treturn Math.min(Math.max(1, Math.round(value)), IMAGE_VARIANT_MAX_AREA)\n}\n\nfunction clampQuality(value: number): number {\n\treturn Math.min(\n\t\tMath.max(IMAGE_VARIANT_MIN_QUALITY, Math.round(value)),\n\t\tIMAGE_VARIANT_MAX_QUALITY,\n\t)\n}\n\n/**\n * Stable string identity of a resolved variant — the cache key input.\n * Two requests produce the same identity iff they render identically.\n */\nexport function imageVariantCanonical(variant: ResolvedImageVariant): string {\n\treturn [\n\t\tvariant.format,\n\t\tvariant.fit,\n\t\tvariant.maxArea,\n\t\tvariant.webpQuality,\n\t\tvariant.avifQuality,\n\t].join(\":\")\n}\n\n/**\n * Encode a variant request as the file route's query string. Always\n * carries `size=preview` so an older server that does not know the\n * variant parameters still degrades to its default preview instead of\n * serving the original bytes.\n */\nexport function imageVariantQuery(spec: ImageVariantSpec): string {\n\tconst params: string[] = [\"size=preview\"]\n\tif (spec.format !== undefined) params.push(`fmt=${spec.format}`)\n\tif (spec.fit !== undefined) params.push(`fit=${spec.fit}`)\n\tif (spec.maxArea !== undefined) params.push(`area=${spec.maxArea}`)\n\tif (spec.quality !== undefined) params.push(`q=${spec.quality}`)\n\treturn params.join(\"&\")\n}\n"]}