@yaebal/preview 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neverlane
+
+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,77 @@
+# @yaebal/preview
+
+> ⚠️ **experimental / wip.** api and rendering may change without notice. not ready for production.
+
+render a telegram-style chat from plain objects to an **SVG string** — rich text, every
+common media type, the lot. zero runtime, no `<foreignObject>` (so it rasterizes and
+survives github's SVG sanitizer). media fields use the real `@yaebal/types` shapes, so you
+can hand it a `ctx.message` almost verbatim. drop the result into docs, a README, or a
+landing page.
+
+## install
+
+```sh
+pnpm add @yaebal/preview
+```
+
+## use
+
+```ts
+import { renderChat } from "@yaebal/preview";
+import { md } from "@yaebal/fmt"; // optional — produces { text, entities }
+
+const svg = renderChat(
+	[
+		{ from: "user", text: "/start", time: "23:33", status: "read" },
+		{ from: "bot", name: "yaebal", ...md`Hello, **unknown** person`, time: "23:33" },
+		{ from: "bot", name: "yaebal", photo: [], src: "cat.jpg", caption: "a cat" },
+		{ from: "bot", name: "yaebal", voice: { duration: 7 } },
+		{ from: "bot", name: "yaebal", buttons: [["Useless button"]] },
+	],
+	{ theme: "light", width: 400 },
+);
+
+await writeFile("chat.svg", svg); // it's just a string
+```
+
+## messages
+
+| field                                  | meaning                                                                                                                               |
+|:---------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------|
+| `from`                                 | `"user"` → outgoing (right, ticks) · `"bot"` → incoming (left, avatar)                                                                |
+| `text`                                 | message text — wrapped automatically                                                                                                  |
+| `entities`                             | telegram `MessageEntity[]` — bold/italic/underline/strike/code/spoiler/link. spread `@yaebal/fmt`'s `md`/`html` to get these for free |
+| `caption` / `captionEntities`          | text under a media message                                                                                                            |
+| `time` · `status` · `buttons` · `name` | time · ticks (`sent`/`delivered`/`read`) · keyboard rows · sender label + avatar                                                      |
+
+## media
+
+all use the real `@yaebal/types` shapes. for picture-like media add `src` (a URL/data-URI)
+to show real pixels — a `file_id` has none, so without `src` you get a clean placeholder.
+
+| field                | renders as                                            |
+|:---------------------|:------------------------------------------------------|
+| `photo`              | image (or placeholder) + optional `caption`           |
+| `sticker`            | standalone image, or its `emoji` big                  |
+| `animation`          | image + `GIF` badge                                   |
+| `video`              | image + play button + duration                        |
+| `voice`              | waveform + duration                                   |
+| `audio`              | play disc + title / performer                         |
+| `document`           | file icon + name + size                               |
+| `venue` / `location` | map tile + pin (+ title/address)                      |
+| `contact`            | avatar + name + phone                                 |
+| `poll`               | question + options with percentage bars               |
+
+add `spoiler: true` to cover picture media.
+
+## options
+
+| option   | default      | meaning                                 |
+|:---------|:-------------|:----------------------------------------|
+| `theme`  | `"light"`    | `"light"` (green wallpaper) or `"dark"` |
+| `width`  | `380`        | canvas width in px                      |
+| `avatar` | name initial | override the incoming avatar glyph      |
+
+---
+
+part of [**yaebal**](https://github.com/neverlane/yaebal) — a type-safe, runtime-agnostic Telegram Bot API framework. MIT.

package/lib/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @yaebal/preview — render a telegram-style chat from plain objects to an SVG string.
+ * zero runtime, no `<foreignObject>` (so it rasterizes and survives github's SVG
+ * sanitizer). media fields use the real `@yaebal/types` shapes, so you can hand it a
+ * `ctx.message` almost verbatim; add `src` to show real pixels (a `file_id` has none).
+ *
+ *   import { renderChat } from "@yaebal/preview";
+ *   import { md } from "@yaebal/fmt";
+ *
+ *   renderChat([
+ *     { from: "user", text: "/start", time: "23:33", status: "read" },
+ *     { from: "bot", name: "yaebal", ...md`hello, **unknown** person`, time: "23:33" },
+ *     { from: "bot", name: "yaebal", photo: [], src: "cat.jpg", caption: "a cat" },
+ *     { from: "bot", name: "yaebal", voice: { duration: 7 } },
+ *     { from: "bot", name: "yaebal", poll: { question: "tabs?", options: [...] } },
+ *   ], { theme: "light" });
+ */
+import type { Animation, Audio, Contact, Document, Location, MessageEntity, PhotoSize, Poll, Sticker, Venue, Video, Voice } from "@yaebal/types";
+export type Side = "user" | "bot";
+export type TickStatus = "sent" | "delivered" | "read";
+export interface ChatMessage {
+    from: Side;
+    /** sender label (incoming); also drives the avatar initial + colour. */
+    name?: string;
+    time?: string;
+    /** outgoing read receipt (ticks). ignored for incoming. */
+    status?: TickStatus;
+    /** keyboard rows rendered as buttons under the message. */
+    buttons?: string[][];
+    /** message text. spread `@yaebal/fmt`'s `md`/`html` to also pass `entities`. */
+    text?: string;
+    /** telegram entities for `text` (bold/italic/code/link/spoiler/…). */
+    entities?: MessageEntity[];
+    /** caption for a media message. */
+    caption?: string;
+    /** telegram entities for `caption`. */
+    captionEntities?: MessageEntity[];
+    /** real image/thumb URL or data-URI for the picture-like media below (a `file_id` can't render). */
+    src?: string;
+    /** cover the media with a spoiler. */
+    spoiler?: boolean;
+    photo?: PhotoSize[];
+    sticker?: Sticker;
+    animation?: Animation;
+    video?: Video;
+    voice?: Voice;
+    audio?: Audio;
+    document?: Document;
+    venue?: Venue;
+    location?: Location;
+    contact?: Contact;
+    poll?: Poll;
+}
+export interface RenderOptions {
+    /** default `"light"` (the green-wallpaper look). */
+    theme?: "dark" | "light";
+    /** canvas width in px. defaults to `380`. */
+    width?: number;
+    /** override the avatar glyph for incoming messages (else the name's initial). */
+    avatar?: string;
+}
+/** render a telegram-style chat to an SVG string. */
+export declare function renderChat(messages: ChatMessage[], options?: RenderOptions): string;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACX,SAAS,EACT,KAAK,EACL,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,aAAa,EACb,SAAS,EACT,IAAI,EACJ,OAAO,EACP,KAAK,EACL,KAAK,EACL,KAAK,EACL,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,KAAK,CAAC;AAClC,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAEvD,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,IAAI,CAAC;IACX,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IAErB,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,eAAe,CAAC,EAAE,aAAa,EAAE,CAAC;IAElC,oGAAoG;IACpG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;IAGlB,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,aAAa;IAC7B,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AA6cD,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAiVvF"}