@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/core/schedule/describe.js

@@ -0,0 +1,74 @@
+// src/core/schedule/describe.ts
+const EN = {
+	daily: (at) => `Every day at ${at}`,
+	weekdays: (at) => `Every weekday (Mon–Fri) at ${at}`,
+	weekends: (at) => `Every weekend (Sat, Sun) at ${at}`,
+	weekly: (days, at) => `Every ${days} at ${at}`,
+	monthly: (day, at) => `Every month on day ${day} at ${at}${day > 28 ? " (or the last day)" : ""}`,
+	monthlyLast: (at) => `Every month on the last day at ${at}`,
+	once: (date, at) => `Once on ${date} at ${at}`,
+	cron: (expr) => `Custom schedule (cron ${expr})`,
+	days: {
+		mon: "Mon",
+		tue: "Tue",
+		wed: "Wed",
+		thu: "Thu",
+		fri: "Fri",
+		sat: "Sat",
+		sun: "Sun"
+	},
+	list: (items) => items.join(", ")
+};
+const WORDS = {
+	en: EN,
+	mr: {
+		daily: (at) => `दररोज ${at} वाजता`,
+		weekdays: (at) => `दर सोमवार ते शुक्रवार ${at} वाजता`,
+		weekends: (at) => `दर शनिवार व रविवार ${at} वाजता`,
+		weekly: (days, at) => `दर ${days} ${at} वाजता`,
+		monthly: (day, at) => `दर महिन्याच्या ${day} तारखेला ${at} वाजता${day > 28 ? " (किंवा शेवटच्या दिवशी)" : ""}`,
+		monthlyLast: (at) => `दर महिन्याच्या शेवटच्या दिवशी ${at} वाजता`,
+		once: (date, at) => `एकदा, ${date} रोजी ${at} वाजता`,
+		cron: (expr) => `सानुकूल वेळापत्रक (cron ${expr})`,
+		days: {
+			mon: "सोम",
+			tue: "मंगळ",
+			wed: "बुध",
+			thu: "गुरु",
+			fri: "शुक्र",
+			sat: "शनि",
+			sun: "रवि"
+		},
+		list: (items) => items.join(", ")
+	}
+};
+const ORDER = [
+	"mon",
+	"tue",
+	"wed",
+	"thu",
+	"fri",
+	"sat",
+	"sun"
+];
+/** Human sentence for a schedule rule in `en` or `mr` (other locales fall back to `en`), for example "Every day at 09:00". */
+function describeRule(rule, locale = "en") {
+	const w = WORDS[locale.split("-")[0] ?? "en"] ?? EN;
+	switch (rule.kind) {
+		case "daily": return w.daily(rule.at);
+		case "weekly": {
+			const days = ORDER.filter((d) => rule.days.includes(d));
+			if (days.length === 7) return w.daily(rule.at);
+			if (days.join() === "mon,tue,wed,thu,fri") return w.weekdays(rule.at);
+			if (days.join() === "sat,sun") return w.weekends(rule.at);
+			return w.weekly(w.list(days.map((d) => w.days[d])), rule.at);
+		}
+		case "monthly": return rule.day === "last" ? w.monthlyLast(rule.at) : w.monthly(rule.day, rule.at);
+		case "once": {
+			const [date = "", at = ""] = rule.at.split("T");
+			return w.once(date, at);
+		}
+		case "cron": return w.cron(rule.expr.trim());
+	}
+}
+export { describeRule };

package/dist/core/schedule/index.d.ts

@@ -0,0 +1,4 @@
+import { describeRule } from "./describe.js";
+import { RuleCheck, ScheduleErrorCode, nextRuns, validateRule } from "./rule.js";
+import { isValidTimeZone } from "./tz.js";
+export { RuleCheck, ScheduleErrorCode, describeRule, isValidTimeZone, nextRuns, validateRule };

package/dist/core/schedule/policy.d.ts

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

package/dist/core/schedule/policy.js

@@ -0,0 +1,37 @@
+import { localParts } from "./tz.js";
+import { Cron } from "croner";
+// src/core/schedule/policy.ts
+/**
+* What to do with a claimed slot. Within `graceMin` of the planned time it always runs; later, `skip` writes a
+* skipped run and `run_once` runs it once (catch-up runs only the latest slot; the caller advances past the rest).
+*/
+function decideMissed(input) {
+	if (input.now - input.nextRunAt <= Math.max(0, input.graceMin) * 6e4) return "run";
+	return input.policy === "skip" ? "skip" : "run";
+}
+function minutes(at) {
+	const [h, m] = at.split(":").map(Number);
+	return (h ?? 0) * 60 + (m ?? 0);
+}
+/** True when the local wall time of `now` is inside the window (`from` ≤ t < `to`, wrapping past midnight). */
+function inQuietHours(quiet, tz, now) {
+	const from = minutes(quiet.from);
+	const to = minutes(quiet.to);
+	if (from === to) return false;
+	const p = localParts(now, quiet.tz ?? tz);
+	const t = p.hour * 60 + p.minute;
+	return from < to ? t >= from && t < to : t >= from || t < to;
+}
+/**
+* When a held message may be sent: the next local `to` time (epoch ms) if `now` is inside quiet hours, else null.
+* `quiet.tz` wins over `tz` (the chat's zone). DST follows croner (a `to` inside a gap is shifted forward).
+*/
+function quietUntil(quiet, tz, now) {
+	if (!quiet || !inQuietHours(quiet, tz, now)) return null;
+	const [h, m] = quiet.to.split(":").map(Number);
+	return new Cron(`${m ?? 0} ${h ?? 0} * * *`, {
+		timezone: quiet.tz ?? tz,
+		paused: true
+	}).nextRun(new Date(now))?.getTime() ?? null;
+}
+export { decideMissed, inQuietHours, quietUntil };

package/dist/core/schedule/rule.d.ts

@@ -0,0 +1,25 @@
+import { ScheduleRule } from "../../contracts/schedules.js";
+/** Problem codes a schedule rule check can fail with. */
+export type ScheduleErrorCode = "schedule_rule_invalid" | "timezone_invalid";
+/** Result of {@link validateRule}; `next` is the first run (epoch ms UTC), or null if none. */
+export type RuleCheck = {
+  ok: true;
+  rule: ScheduleRule;
+  next: number | null;
+} | {
+  ok: false;
+  code: ScheduleErrorCode;
+  message: string;
+};
+/**
+ * Validates a rule for saving. With `now`, a `once` rule in the past and a cron that never fires are errors.
+ * Returns the next run so callers can store `next_run_at`.
+ */
+export declare function validateRule(input: unknown, tz: string, opts?: {
+  now?: number;
+}): RuleCheck;
+/**
+ * The next `count` run instants (epoch ms, ascending) strictly after `after`, for a rule in `tz`.
+ * Monthly days 29–31 run on the last day of shorter months. Throws `ScheduleError` on an invalid rule or zone.
+ */
+export declare function nextRuns(input: ScheduleRule | unknown, tz: string, after: number, count?: number): number[];

package/dist/core/schedule/rule.js

@@ -0,0 +1,142 @@
+import { ScheduleRule } from "../../contracts/schedules.js";
+import { daysInMonth, isValidTimeZone, localParts } from "./tz.js";
+import { Cron } from "croner";
+// src/core/schedule/rule.ts
+/** Thrown for an invalid rule or IANA zone; `code` is a plugin problem code. */
+var ScheduleError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "ScheduleError";
+		this.code = code;
+	}
+};
+const DOW = {
+	sun: 0,
+	mon: 1,
+	tue: 2,
+	wed: 3,
+	thu: 4,
+	fri: 5,
+	sat: 6
+};
+function clock(at) {
+	const [h, m] = at.split(":").map(Number);
+	return {
+		h: h ?? 0,
+		m: m ?? 0
+	};
+}
+/** The croner pattern(s) for a rule. Monthly days 29–31 also need the last-day pattern (short months). */
+function rulePatterns(rule) {
+	switch (rule.kind) {
+		case "daily": {
+			const { h, m } = clock(rule.at);
+			return [`${m} ${h} * * *`];
+		}
+		case "weekly": {
+			const { h, m } = clock(rule.at);
+			return [`${m} ${h} * * ${[...new Set(rule.days.map((d) => DOW[d] ?? 0))].sort((a, b) => a - b).join(",")}`];
+		}
+		case "monthly": {
+			const { h, m } = clock(rule.at);
+			if (rule.day === "last") return [`${m} ${h} L * *`];
+			return rule.day > 28 ? [`${m} ${h} ${rule.day} * *`, `${m} ${h} L * *`] : [`${m} ${h} ${rule.day} * *`];
+		}
+		case "cron": return [rule.expr.trim().split(/\s+/).join(" ")];
+		case "once": return [`${rule.at}:00`];
+	}
+}
+function cron(pattern, tz) {
+	try {
+		return new Cron(pattern, {
+			timezone: tz,
+			paused: true
+		});
+	} catch (e) {
+		throw new ScheduleError("schedule_rule_invalid", e instanceof Error ? e.message.replace(/^CronPattern:\s*/, "") : "invalid pattern");
+	}
+}
+/** Parses and checks a rule + zone. Throws `ScheduleError`. */
+function parseRule(input, tz) {
+	if (!isValidTimeZone(tz)) throw new ScheduleError("timezone_invalid", `unknown time zone "${String(tz)}"`);
+	const r = ScheduleRule.safeParse(input);
+	if (!r.success) {
+		const issue = r.error.issues[0];
+		throw new ScheduleError("schedule_rule_invalid", `${issue?.path.length ? `${issue.path.join(".")}: ` : ""}${issue?.message ?? "invalid rule"}`);
+	}
+	for (const p of rulePatterns(r.data)) cron(p, tz);
+	return r.data;
+}
+/**
+* Validates a rule for saving. With `now`, a `once` rule in the past and a cron that never fires are errors.
+* Returns the next run so callers can store `next_run_at`.
+*/
+function validateRule(input, tz, opts = {}) {
+	try {
+		const rule = parseRule(input, tz);
+		const now = opts.now;
+		if (now === void 0) return {
+			ok: true,
+			rule,
+			next: null
+		};
+		const next = nextRuns(rule, tz, now, 1)[0] ?? null;
+		if (next === null) return {
+			ok: false,
+			code: "schedule_rule_invalid",
+			message: rule.kind === "once" ? "the time is in the past" : "the rule never runs"
+		};
+		return {
+			ok: true,
+			rule,
+			next
+		};
+	} catch (e) {
+		if (e instanceof ScheduleError) return {
+			ok: false,
+			code: e.code,
+			message: e.message
+		};
+		throw e;
+	}
+}
+/**
+* The next `count` run instants (epoch ms, ascending) strictly after `after`, for a rule in `tz`.
+* Monthly days 29–31 run on the last day of shorter months. Throws `ScheduleError` on an invalid rule or zone.
+*/
+function nextRuns(input, tz, after, count = 1) {
+	const rule = parseRule(input, tz);
+	const n = Math.max(0, Math.min(1e3, Math.floor(count)));
+	const [main, last] = rulePatterns(rule).map((p) => cron(p, tz));
+	if (!main) return [];
+	const out = [];
+	const wanted = rule.kind === "monthly" && typeof rule.day === "number" ? rule.day : null;
+	const nextLast = (from) => {
+		if (!last || wanted === null) return null;
+		let cursor = from;
+		for (let k = 0; k < 13; k++) {
+			const d = last.nextRun(new Date(cursor));
+			if (!d) return null;
+			const p = localParts(d.getTime(), tz);
+			if (daysInMonth(p.year, p.month) < wanted) return d.getTime();
+			cursor = d.getTime();
+		}
+		return null;
+	};
+	let cursor = after;
+	while (out.length < n) {
+		const a = main.nextRun(new Date(cursor))?.getTime() ?? null;
+		const b = nextLast(cursor);
+		const next = a === null ? b : b === null ? a : Math.min(a, b);
+		if (next === null || next <= cursor) break;
+		out.push(next);
+		cursor = next;
+	}
+	return out;
+}
+/** Convenience: the next run after `after`, or null when the rule is finished. */
+function nextRun(rule, tz, after) {
+	return nextRuns(rule, tz, after, 1)[0] ?? null;
+}
+export { ScheduleError, nextRun, nextRuns, parseRule, rulePatterns, validateRule };

package/dist/core/schedule/tz.d.ts

@@ -0,0 +1,2 @@
+/** True for IANA names Intl knows (`Asia/Kolkata`, `UTC`). Offsets like `+05:30` are rejected. */
+export declare function isValidTimeZone(tz: unknown): tz is string;

package/dist/core/schedule/tz.js

@@ -0,0 +1,59 @@
+// src/core/schedule/tz.ts
+const valid = /* @__PURE__ */ new Map();
+/** True for IANA names Intl knows (`Asia/Kolkata`, `UTC`). Offsets like `+05:30` are rejected. */
+function isValidTimeZone(tz) {
+	if (typeof tz !== "string" || tz.length === 0 || tz.length > 64 || /^[+-]/.test(tz)) return false;
+	const hit = valid.get(tz);
+	if (hit !== void 0) return hit;
+	let ok;
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone: tz });
+		ok = true;
+	} catch {
+		ok = false;
+	}
+	valid.set(tz, ok);
+	return ok;
+}
+const formatters = /* @__PURE__ */ new Map();
+const WEEKDAY = {
+	Sun: 0,
+	Mon: 1,
+	Tue: 2,
+	Wed: 3,
+	Thu: 4,
+	Fri: 5,
+	Sat: 6
+};
+/** Wall-clock parts of an instant in a zone. */
+function localParts(epochMs, tz) {
+	let f = formatters.get(tz);
+	if (!f) {
+		f = new Intl.DateTimeFormat("en-US", {
+			timeZone: tz,
+			hourCycle: "h23",
+			year: "numeric",
+			month: "numeric",
+			day: "numeric",
+			hour: "numeric",
+			minute: "numeric",
+			weekday: "short"
+		});
+		formatters.set(tz, f);
+	}
+	const out = {
+		year: 0,
+		month: 0,
+		day: 0,
+		hour: 0,
+		minute: 0,
+		weekday: 0
+	};
+	for (const p of f.formatToParts(epochMs)) if (p.type === "weekday") out.weekday = WEEKDAY[p.value] ?? 0;
+	else if (p.type === "year" || p.type === "month" || p.type === "day" || p.type === "hour" || p.type === "minute") out[p.type] = Number(p.value);
+	return out;
+}
+function daysInMonth(year, month) {
+	return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+export { daysInMonth, isValidTimeZone, localParts };

package/dist/core/split/plain.d.ts

@@ -0,0 +1,2 @@
+/** Strips tags and decodes entities. Links keep their URL after the label: `Order (https://…)`. */
+export declare function toPlainText(html: string): string;

package/dist/core/split/plain.js

@@ -0,0 +1,23 @@
+import { decodeEntities } from "../html/escape.js";
+import { tokenizeHtml } from "../html/tokenize.js";
+// src/core/split/plain.ts
+/** Strips tags and decodes entities. Links keep their URL after the label: `Order (https://…)`. */
+function toPlainText(html) {
+	let out = "";
+	const links = [];
+	for (const tok of tokenizeHtml(html)) if (tok.type === "text") out += tok.raw;
+	else if (tok.type === "entity") out += tok.text;
+	else if (tok.type === "open" && tok.name === "a") links.push({
+		href: tok.attrs.href ?? "",
+		from: out.length
+	});
+	else if (tok.type === "close" && tok.name === "a") {
+		const link = links.pop();
+		if (!link) continue;
+		const href = decodeEntities(link.href);
+		const label = out.slice(link.from).trim();
+		if (href && href !== label && /^https?:\/\//i.test(href)) out += ` (${href})`;
+	}
+	return out;
+}
+export { toPlainText };

package/dist/core/split/split.d.ts

@@ -0,0 +1,15 @@
+/** `sendMessage` / `editMessageText` text limit. */
+export declare const TEXT_LIMIT = 4096;
+/** Caption limit (`sendDocument`, `sendPhoto`, …). */
+export declare const CAPTION_LIMIT = 1024;
+/** Visible length of Telegram HTML as Telegram counts it (UTF-16 code units of the parsed text). */
+export declare function visibleLength(html: string): number;
+/** Options for {@link splitMessage}. */
+export interface SplitOptions {
+  /** Max visible length per part (default 4096). */
+  limit?: number;
+  /** Limit for the first part only (for example 1024 when it becomes a caption). */
+  firstLimit?: number;
+}
+/** Splits Telegram HTML into parts of at most `limit` visible chars, keeping tags balanced in every part (prefers paragraph, line, then word breaks). */
+export declare function splitMessage(html: string, opts?: SplitOptions): string[];

package/dist/core/split/split.js

@@ -0,0 +1,158 @@
+import { tokenizeHtml } from "../html/tokenize.js";
+// src/core/split/split.ts
+/** `sendMessage` / `editMessageText` text limit. */
+const TEXT_LIMIT = 4096;
+/** Caption limit (`sendDocument`, `sendPhoto`, …). */
+const CAPTION_LIMIT = 1024;
+const ATOMIC = /* @__PURE__ */ new Set(["tg-emoji", "tg-time"]);
+let segmenter;
+function atomize(html) {
+	segmenter ??= new Intl.Segmenter(void 0, { granularity: "grapheme" });
+	const atoms = [];
+	for (const tok of tokenizeHtml(html)) if (tok.type === "open") atoms.push({
+		t: "open",
+		raw: tok.raw,
+		name: tok.name
+	});
+	else if (tok.type === "close") atoms.push({
+		t: "close",
+		raw: tok.raw,
+		name: tok.name
+	});
+	else if (tok.type === "entity") atoms.push({
+		t: "vis",
+		raw: tok.raw,
+		ch: tok.text,
+		w: tok.text.length
+	});
+	else for (const { segment } of segmenter.segment(tok.raw)) atoms.push({
+		t: "vis",
+		raw: segment,
+		ch: segment,
+		w: segment.length
+	});
+	return atoms;
+}
+function stacks(atoms) {
+	const out = new Array(atoms.length + 1);
+	let s = null;
+	for (let i = 0; i < atoms.length; i++) {
+		out[i] = s;
+		const a = atoms[i];
+		if (a?.t === "open") s = {
+			atom: a,
+			parent: s
+		};
+		else if (a?.t === "close") {
+			let p = s;
+			while (p && p.atom.name !== a.name) p = p.parent;
+			if (p) s = p.parent;
+		}
+	}
+	out[atoms.length] = s;
+	return out;
+}
+const isSpace = (a) => a?.t === "vis" && /^\s+$/.test(a.ch);
+const isNewline = (a) => a?.t === "vis" && /[\n\r]/.test(a.ch);
+function inAtomic(s) {
+	for (let p = s ?? null; p; p = p.parent) if (ATOMIC.has(p.atom.name)) return true;
+	return false;
+}
+/** Visible length of Telegram HTML as Telegram counts it (UTF-16 code units of the parsed text). */
+function visibleLength(html) {
+	let n = 0;
+	for (const a of atomize(html)) if (a.t === "vis") n += a.w;
+	return n;
+}
+/** Splits Telegram HTML into parts of at most `limit` visible chars, keeping tags balanced in every part (prefers paragraph, line, then word breaks). */
+function splitMessage(html, opts = {}) {
+	const limit = Math.max(16, opts.limit ?? 4096);
+	const atoms = atomize(html);
+	const stackAt = stacks(atoms);
+	const parts = [];
+	let start = 0;
+	while (start < atoms.length) {
+		const max = parts.length === 0 ? Math.max(16, opts.firstLimit ?? limit) : limit;
+		let s0 = start;
+		while (s0 < atoms.length && (atoms[s0]?.t !== "vis" || isSpace(atoms[s0]))) s0++;
+		let width = 0;
+		let end = s0;
+		const widthAt = /* @__PURE__ */ new Map();
+		while (end < atoms.length) {
+			const a = atoms[end];
+			const w = a?.t === "vis" ? a.w : 0;
+			if (width + w > max) break;
+			widthAt.set(end, width);
+			width += w;
+			end++;
+		}
+		widthAt.set(end, width);
+		if (end >= atoms.length) {
+			parts.push(emit(atoms, stackAt, start, atoms.length));
+			break;
+		}
+		const cut = chooseCut(atoms, stackAt, s0, end, max, widthAt);
+		parts.push(emit(atoms, stackAt, start, cut));
+		start = cut;
+	}
+	return parts.filter((p) => visibleLength(p) > 0);
+}
+function chooseCut(atoms, stackAt, s0, end, max, widthAt) {
+	const fill = (i) => widthAt.get(i) ?? 0;
+	const prevVisible = (i) => {
+		for (let k = i - 1; k >= s0; k--) {
+			const a = atoms[k];
+			if (a?.t === "vis") return a;
+		}
+	};
+	const scan = (ok, minFill) => {
+		for (let i = end; i > s0; i--) {
+			if (fill(i) < minFill) return null;
+			if (!inAtomic(stackAt[i]) && ok(i)) return i;
+		}
+		return null;
+	};
+	const para = scan((i) => isNewline(atoms[i]) && isNewline(prevVisible(i)), max / 2);
+	if (para !== null) return para;
+	const line = scan((i) => isNewline(atoms[i]), max / 2);
+	if (line !== null) return line;
+	const word = scan((i) => isSpace(atoms[i]), 1);
+	if (word !== null) return word;
+	for (let i = end; i > s0; i--) if (!inAtomic(stackAt[i])) return i;
+	return Math.max(end, s0 + 1);
+}
+function emit(atoms, stackAt, from, to) {
+	const open = [];
+	for (let p = stackAt[from] ?? null; p; p = p.parent) open.unshift(p.atom.raw);
+	const drop = /* @__PURE__ */ new Set();
+	for (let i = from; i < to && (atoms[i]?.t !== "vis" || isSpace(atoms[i])); i++) if (isSpace(atoms[i])) drop.add(i);
+	for (let i = to - 1; i >= from && (atoms[i]?.t !== "vis" || isSpace(atoms[i])); i--) if (isSpace(atoms[i])) drop.add(i);
+	let body = "";
+	for (let i = from; i < to; i++) if (!drop.has(i)) body += atoms[i]?.raw ?? "";
+	let close = "";
+	for (let p = stackAt[to] ?? null; p; p = p.parent) close += `</${p.atom.name}>`;
+	return dropEmptyElements(open.join("") + body + close);
+}
+const EMPTY_RE = /<([a-z][a-z0-9-]*)(?:\s[^>]*)?>(\s*)<\/\1>/g;
+/** Removes elements left empty by a split (`<b></b>`), keeping any whitespace they held. */
+function dropEmptyElements(html) {
+	let prev = "";
+	let out = html;
+	while (out !== prev) {
+		prev = out;
+		out = out.replace(EMPTY_RE, "$2");
+	}
+	return out;
+}
+/** First part as a caption (≤ 1024), the rest as follow-up messages (≤ 4096). */
+function fitCaption(html, opts = {}) {
+	const parts = splitMessage(html, {
+		firstLimit: opts.captionLimit ?? 1024,
+		limit: opts.textLimit ?? 4096
+	});
+	return {
+		caption: parts[0] ?? "",
+		rest: parts.slice(1)
+	};
+}
+export { CAPTION_LIMIT, TEXT_LIMIT, fitCaption, splitMessage, visibleLength };

package/dist/core/template/ast.d.ts

@@ -0,0 +1,58 @@
+/** 1-based source position. */
+export interface Pos {
+  line: number;
+  column: number;
+}
+/** A literal filter argument. */
+export type FilterArg = string | number | boolean;
+/** One `| name: args` filter application. */
+export interface FilterCall extends Pos {
+  name: string;
+  args: FilterArg[];
+}
+/** `{{a.b | filter:arg}}`. `path` is empty for `{{.}}` (the current item). */
+export interface VarNode extends Pos {
+  type: "var";
+  path: string[];
+  filters: FilterCall[];
+}
+/** Literal text, already safe Telegram HTML (stray `& < >` were escaped by the parser). */
+export interface TextNode extends Pos {
+  type: "text";
+  value: string;
+}
+/** `{{#path}}…{{/path}}` or `{{^path}}…{{/path}}`. */
+export interface SectionNode extends Pos {
+  type: "section" | "inverted";
+  path: string[];
+  children: Node[];
+}
+export type AttrPart = {
+  type: "text";
+  value: string;
+} | VarNode;
+export interface Attr {
+  name: string;
+  /** null for a boolean attribute (`<blockquote expandable>`). */
+  value: AttrPart[] | null;
+}
+/** One allowed Telegram HTML element written in the template. */
+export interface ElementNode extends Pos {
+  type: "element";
+  name: string;
+  attrs: Attr[];
+  children: Node[];
+}
+export type Node = TextNode | VarNode | SectionNode | ElementNode;
+/** Root of a parsed template (from {@link parseTemplate}). */
+export interface TemplateAst {
+  type: "root";
+  children: Node[];
+}
+/** Machine code of a template error. */
+export type TemplateErrorCode = "syntax" | "raw_not_allowed" | "tag_not_allowed" | "attr_invalid" | "url_invalid" | "nesting_invalid" | "unclosed" | "variable_unknown" | "section_invalid" | "variable_type" | "filter_unknown" | "filter_args" | "render";
+/** Compatible with the `TemplateError` contract, plus a machine `code`. */
+export interface CoreTemplateError extends Pos {
+  code: TemplateErrorCode;
+  message: string;
+}

package/dist/core/template/ast.js

@@ -0,0 +1,5 @@
+// src/core/template/ast.ts
+function pathText(path) {
+	return path.length === 0 ? "." : path.join(".");
+}
+export { pathText };