balagan 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gal Schlezinger
+
+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,48 @@
+# balagan
+
+🙅 put some order to all of this mess
+
+## Install
+
+```bash
+npm i balagan
+```
+
+## Usage
+
+```ts
+import { help, hint, note, code, frame, inline } from "balagan";
+
+// Styled messages
+console.log(help("run with --verbose for more info"));
+console.log(hint("try using a different port"));
+console.log(note("this feature is experimental"));
+
+// Inline code styling
+console.log(`Use ${code("npm start")} to begin`);
+
+// Frame content in a tree structure
+console.log(
+  frame("2 errors emitted", ["Missing semicolon", "Undefined variable"]),
+);
+
+// Annotate code with explanations (compiler-style)
+console.log(inline`function ${["hello", "invalid name"]}() {}`);
+// Output:
+// function hello() {}
+//          ──┬──
+//            ╰▶ invalid name
+```
+
+## API
+
+- `help(msg)` - Blue "help:" prefixed message
+- `hint(msg)` - Blue "hint:" prefixed message
+- `note(msg)` - Blue "note:" prefixed message
+- `code(str)` - Inline code with backticks
+- `frame(text, contents)` - Tree-framed content
+- `inline` - Template tag for inline annotations with underlines
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,157 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var pico = require('picocolors');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var pico__default = /*#__PURE__*/_interopDefault(pico);
+
+const styles = {
+    info: pico__default.default.blue,
+    help: pico__default.default.cyan,
+    warn: pico__default.default.yellow,
+    error: pico__default.default.red
+};
+function help(messages) {
+    const message = Array.isArray(messages) ? messages.join("\n") : messages;
+    return styles.help(`${pico__default.default.bold("help:")} ${message}`);
+}
+function hint(messages) {
+    const message = Array.isArray(messages) ? messages.join("\n") : messages;
+    return styles.info(`${pico__default.default.bold("hint:")} ${message}`);
+}
+function note(messages) {
+    const message = Array.isArray(messages) ? messages.join("\n") : messages;
+    return styles.info(`${pico__default.default.bold("note:")} ${message}`);
+}
+function code(str) {
+    return pico__default.default.italic(`${pico__default.default.dim("`")}${str}${pico__default.default.dim("`")}`);
+}
+function frame(text, contents) {
+    const result = [
+        text
+    ];
+    contents.forEach((content, index)=>{
+        const lines = content.split("\n");
+        const isLastContent = index === contents.length - 1;
+        const firstLinePrefix = isLastContent ? "╰▶ " : "├▶ ";
+        const continuationPrefix = isLastContent ? "   " : "│  ";
+        const framedLines = lines.map((line, lineIndex)=>{
+            const prefix = lineIndex === 0 ? firstLinePrefix : continuationPrefix;
+            return `${prefix}${line}`;
+        });
+        result.push(...framedLines);
+    });
+    return result.join("\n");
+}
+const identity = (s)=>s;
+function getMarkerMidpoint(marker) {
+    const textLen = marker.endCol - marker.startCol;
+    return marker.startCol + Math.floor(textLen / 2);
+}
+function buildUnderline(markers) {
+    const parts = [];
+    let pos = 0;
+    for (const marker of markers){
+        const textLen = marker.endCol - marker.startCol;
+        const midPoint = Math.floor(textLen / 2);
+        if (marker.startCol > pos) {
+            parts.push(" ".repeat(marker.startCol - pos));
+            pos = marker.startCol;
+        }
+        const segment = `${"─".repeat(midPoint)}┬${"─".repeat(textLen - midPoint - 1)}`;
+        const colorFn = marker.color ?? identity;
+        parts.push(colorFn(segment));
+        pos += textLen;
+    }
+    return parts.join("");
+}
+function buildExplanationLine(marker, midCol, remainingMids, isOnlyMarker) {
+    let line = "╰";
+    let pos = midCol + 1;
+    for (const nextMid of remainingMids){
+        while(pos < nextMid){
+            line += "─";
+            pos++;
+        }
+        line += "┼";
+        pos++;
+    }
+    const arrow = isOnlyMarker ? "▶ " : "─▶ ";
+    line += arrow + marker.explain;
+    const colorFn = marker.color ?? identity;
+    return " ".repeat(midCol) + colorFn(line);
+}
+/**
+ * @example
+ * inline`function ${{text: "hello", explain: "name not allowed bro"}}() {\n  return 666\n}`;
+ * =>
+ * function hello() {
+ *          ──┬──
+ *            ╰▶ name not allowed bro
+ *   return 666
+ * }
+ */ function inline(text, ...values) {
+    const resultLines = [];
+    let currentLine = "";
+    let currentLineVisualLen = 0;
+    let pendingMarkers = [];
+    const flushLine = ()=>{
+        resultLines.push(currentLine);
+        if (pendingMarkers.length === 0) {
+            currentLine = "";
+            currentLineVisualLen = 0;
+            return;
+        }
+        const markerMids = pendingMarkers.map(getMarkerMidpoint);
+        resultLines.push(buildUnderline(pendingMarkers));
+        for(let i = 0; i < pendingMarkers.length; i++){
+            const line = buildExplanationLine(pendingMarkers[i], markerMids[i], markerMids.slice(i + 1), pendingMarkers.length === 1);
+            resultLines.push(line);
+        }
+        pendingMarkers = [];
+        currentLine = "";
+        currentLineVisualLen = 0;
+    };
+    for(let i = 0; i < text.length; i++){
+        const segment = text[i];
+        const lines = segment.split("\n");
+        for(let j = 0; j < lines.length; j++){
+            if (j > 0) {
+                flushLine();
+            }
+            currentLine += lines[j];
+            currentLineVisualLen += lines[j].length;
+        }
+        if (i < values.length) {
+            const val = values[i];
+            const value = !Array.isArray(val) ? val : {
+                text: val[0],
+                explain: val[1],
+                ...val[2]
+            };
+            const startCol = currentLineVisualLen;
+            const colorFn = value.color ?? ((s)=>s);
+            currentLine += colorFn(value.text);
+            currentLineVisualLen += value.text.length;
+            const endCol = currentLineVisualLen;
+            pendingMarkers.push({
+                startCol,
+                endCol,
+                explain: value.explain,
+                color: value.color
+            });
+        }
+    }
+    if (currentLine || pendingMarkers.length > 0) {
+        flushLine();
+    }
+    return resultLines.join("\n");
+}
+
+exports.code = code;
+exports.frame = frame;
+exports.help = help;
+exports.hint = hint;
+exports.inline = inline;
+exports.note = note;

package/dist/index.d.cts

@@ -0,0 +1,26 @@
+declare function help(messages: string | string[]): string;
+declare function hint(messages: string | string[]): string;
+declare function note(messages: string | string[]): string;
+declare function code(str: string): string;
+declare function frame(text: string, contents: string[]): string;
+interface Explain {
+    text: string;
+    explain: string;
+    /** adds ansi coloring */
+    color?: (s: string) => string;
+}
+type Explainish = Explain | [text: string, explain: string, opts?: Pick<Explain, "color">];
+/**
+ * @example
+ * inline`function ${{text: "hello", explain: "name not allowed bro"}}() {\n  return 666\n}`;
+ * =>
+ * function hello() {
+ *          ──┬──
+ *            ╰▶ name not allowed bro
+ *   return 666
+ * }
+ */
+declare function inline(text: TemplateStringsArray, ...values: Explainish[]): string;
+
+export { code, frame, help, hint, inline, note };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sources":["../src/index.ts"],"sourcesContent":["import pico from \"picocolors\";\n\nconst styles = {\n  info: pico.blue,\n  help: pico.cyan,\n  warn: pico.yellow,\n  error: pico.red,\n};\n\nexport function help(messages: string | string[]) {\n  const message = Array.isArray(messages) ? messages.join(\"\\n\") : messages;\n  return styles.help(`${pico.bold(\"help:\")} ${message}`);\n}\n\nexport function hint(messages: string | string[]) {\n  const message = Array.isArray(messages) ? messages.join(\"\\n\") : messages;\n  return styles.info(`${pico.bold(\"hint:\")} ${message}`);\n}\n\nexport function note(messages: string | string[]) {\n  const message = Array.isArray(messages) ? messages.join(\"\\n\") : messages;\n  return styles.info(`${pico.bold(\"note:\")} ${message}`);\n}\n\nexport function code(str: string) {\n  return pico.italic(`${pico.dim(\"`\")}${str}${pico.dim(\"`\")}`);\n}\n\nexport function frame(text: string, contents: string[]): string {\n  const result = [text];\n\n  contents.forEach((content, index) => {\n    const lines = content.split(\"\\n\");\n    const isLastContent = index === contents.length - 1;\n\n    const firstLinePrefix = isLastContent ? \"╰▶ \" : \"├▶ \";\n    const continuationPrefix = isLastContent ? \"   \" : \"│  \";\n\n    const framedLines = lines.map((line, lineIndex) => {\n      const prefix = lineIndex === 0 ? firstLinePrefix : continuationPrefix;\n      return `${prefix}${line}`;\n    });\n\n    result.push(...framedLines);\n  });\n\n  return result.join(\"\\n\");\n}\n\ninterface Explain {\n  text: string;\n  explain: string;\n  /** adds ansi coloring */\n  color?: (s: string) => string;\n}\n\ntype Explainish = Explain | [text: string, explain: string, opts?: Pick<Explain, \"color\">];\n\ntype Marker = {\n  startCol: number;\n  endCol: number;\n  explain: string;\n  color?: (s: string) => string;\n};\n\nconst identity = (s: string) => s;\n\nfunction getMarkerMidpoint(marker: Marker): number {\n  const textLen = marker.endCol - marker.startCol;\n  return marker.startCol + Math.floor(textLen / 2);\n}\n\nfunction buildUnderline(markers: Marker[]): string {\n  const parts: string[] = [];\n  let pos = 0;\n  for (const marker of markers) {\n    const textLen = marker.endCol - marker.startCol;\n    const midPoint = Math.floor(textLen / 2);\n\n    if (marker.startCol > pos) {\n      parts.push(\" \".repeat(marker.startCol - pos));\n      pos = marker.startCol;\n    }\n    const segment = `${\"─\".repeat(midPoint)}┬${\"─\".repeat(textLen - midPoint - 1)}`;\n    const colorFn = marker.color ?? identity;\n    parts.push(colorFn(segment));\n    pos += textLen;\n  }\n  return parts.join(\"\");\n}\n\nfunction buildExplanationLine(\n  marker: Marker,\n  midCol: number,\n  remainingMids: number[],\n  isOnlyMarker: boolean,\n): string {\n  let line = \"╰\";\n  let pos = midCol + 1;\n\n  for (const nextMid of remainingMids) {\n    while (pos < nextMid) {\n      line += \"─\";\n      pos++;\n    }\n    line += \"┼\";\n    pos++;\n  }\n\n  const arrow = isOnlyMarker ? \"▶ \" : \"─▶ \";\n  line += arrow + marker.explain;\n\n  const colorFn = marker.color ?? identity;\n  return \" \".repeat(midCol) + colorFn(line);\n}\n\n/**\n * @example\n * inline`function ${{text: \"hello\", explain: \"name not allowed bro\"}}() {\\n  return 666\\n}`;\n * =>\n * function hello() {\n *          ──┬──\n *            ╰▶ name not allowed bro\n *   return 666\n * }\n */\nexport function inline(text: TemplateStringsArray, ...values: Explainish[]): string {\n  const resultLines: string[] = [];\n  let currentLine = \"\";\n  let currentLineVisualLen = 0;\n  let pendingMarkers: Marker[] = [];\n\n  const flushLine = () => {\n    resultLines.push(currentLine);\n    if (pendingMarkers.length === 0) {\n      currentLine = \"\";\n      currentLineVisualLen = 0;\n      return;\n    }\n\n    const markerMids = pendingMarkers.map(getMarkerMidpoint);\n\n    resultLines.push(buildUnderline(pendingMarkers));\n\n    for (let i = 0; i < pendingMarkers.length; i++) {\n      const line = buildExplanationLine(\n        pendingMarkers[i],\n        markerMids[i],\n        markerMids.slice(i + 1),\n        pendingMarkers.length === 1,\n      );\n      resultLines.push(line);\n    }\n\n    pendingMarkers = [];\n    currentLine = \"\";\n    currentLineVisualLen = 0;\n  };\n\n  for (let i = 0; i < text.length; i++) {\n    const segment = text[i];\n    const lines = segment.split(\"\\n\");\n\n    for (let j = 0; j < lines.length; j++) {\n      if (j > 0) {\n        flushLine();\n      }\n      currentLine += lines[j];\n      currentLineVisualLen += lines[j].length;\n    }\n\n    if (i < values.length) {\n      const val = values[i];\n      const value: Explain = !Array.isArray(val)\n        ? val\n        : { text: val[0], explain: val[1], ...val[2] };\n      const startCol = currentLineVisualLen;\n      const colorFn = value.color ?? ((s: string) => s);\n      currentLine += colorFn(value.text);\n      currentLineVisualLen += value.text.length;\n      const endCol = currentLineVisualLen;\n      pendingMarkers.push({\n        startCol,\n        endCol,\n        explain: value.explain,\n        color: value.color,\n      });\n    }\n  }\n\n  if (currentLine || pendingMarkers.length > 0) {\n    flushLine();\n  }\n\n  return resultLines.join(\"\\n\");\n}\n"],"names":[],"mappings":"AAAO,iBAAA,IAAA;AACA,iBAAA,IAAA;AACA,iBAAA,IAAA;AACA,iBAAA,IAAA;AACA,iBAAA,KAAA;AACP,UAAA,OAAA;AACA;AACA;AACA;AACA;AACA;AACA,KAAA,UAAA,GAAA,OAAA,0CAAA,IAAA,CAAA,OAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,iBAAA,MAAA,OAAA,oBAAA,aAAA,UAAA;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+declare function help(messages: string | string[]): string;
+declare function hint(messages: string | string[]): string;
+declare function note(messages: string | string[]): string;
+declare function code(str: string): string;
+declare function frame(text: string, contents: string[]): string;
+interface Explain {
+    text: string;
+    explain: string;
+    /** adds ansi coloring */
+    color?: (s: string) => string;
+}
+type Explainish = Explain | [text: string, explain: string, opts?: Pick<Explain, "color">];
+/**
+ * @example
+ * inline`function ${{text: "hello", explain: "name not allowed bro"}}() {\n  return 666\n}`;
+ * =>
+ * function hello() {
+ *          ──┬──
+ *            ╰▶ name not allowed bro
+ *   return 666
+ * }
+ */
+declare function inline(text: TemplateStringsArray, ...values: Explainish[]): string;
+
+export { code, frame, help, hint, inline, note };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sources":["../src/index.ts"],"sourcesContent":["import pico from \"picocolors\";\n\nconst styles = {\n  info: pico.blue,\n  help: pico.cyan,\n  warn: pico.yellow,\n  error: pico.red,\n};\n\nexport function help(messages: string | string[]) {\n  const message = Array.isArray(messages) ? messages.join(\"\\n\") : messages;\n  return styles.help(`${pico.bold(\"help:\")} ${message}`);\n}\n\nexport function hint(messages: string | string[]) {\n  const message = Array.isArray(messages) ? messages.join(\"\\n\") : messages;\n  return styles.info(`${pico.bold(\"hint:\")} ${message}`);\n}\n\nexport function note(messages: string | string[]) {\n  const message = Array.isArray(messages) ? messages.join(\"\\n\") : messages;\n  return styles.info(`${pico.bold(\"note:\")} ${message}`);\n}\n\nexport function code(str: string) {\n  return pico.italic(`${pico.dim(\"`\")}${str}${pico.dim(\"`\")}`);\n}\n\nexport function frame(text: string, contents: string[]): string {\n  const result = [text];\n\n  contents.forEach((content, index) => {\n    const lines = content.split(\"\\n\");\n    const isLastContent = index === contents.length - 1;\n\n    const firstLinePrefix = isLastContent ? \"╰▶ \" : \"├▶ \";\n    const continuationPrefix = isLastContent ? \"   \" : \"│  \";\n\n    const framedLines = lines.map((line, lineIndex) => {\n      const prefix = lineIndex === 0 ? firstLinePrefix : continuationPrefix;\n      return `${prefix}${line}`;\n    });\n\n    result.push(...framedLines);\n  });\n\n  return result.join(\"\\n\");\n}\n\ninterface Explain {\n  text: string;\n  explain: string;\n  /** adds ansi coloring */\n  color?: (s: string) => string;\n}\n\ntype Explainish = Explain | [text: string, explain: string, opts?: Pick<Explain, \"color\">];\n\ntype Marker = {\n  startCol: number;\n  endCol: number;\n  explain: string;\n  color?: (s: string) => string;\n};\n\nconst identity = (s: string) => s;\n\nfunction getMarkerMidpoint(marker: Marker): number {\n  const textLen = marker.endCol - marker.startCol;\n  return marker.startCol + Math.floor(textLen / 2);\n}\n\nfunction buildUnderline(markers: Marker[]): string {\n  const parts: string[] = [];\n  let pos = 0;\n  for (const marker of markers) {\n    const textLen = marker.endCol - marker.startCol;\n    const midPoint = Math.floor(textLen / 2);\n\n    if (marker.startCol > pos) {\n      parts.push(\" \".repeat(marker.startCol - pos));\n      pos = marker.startCol;\n    }\n    const segment = `${\"─\".repeat(midPoint)}┬${\"─\".repeat(textLen - midPoint - 1)}`;\n    const colorFn = marker.color ?? identity;\n    parts.push(colorFn(segment));\n    pos += textLen;\n  }\n  return parts.join(\"\");\n}\n\nfunction buildExplanationLine(\n  marker: Marker,\n  midCol: number,\n  remainingMids: number[],\n  isOnlyMarker: boolean,\n): string {\n  let line = \"╰\";\n  let pos = midCol + 1;\n\n  for (const nextMid of remainingMids) {\n    while (pos < nextMid) {\n      line += \"─\";\n      pos++;\n    }\n    line += \"┼\";\n    pos++;\n  }\n\n  const arrow = isOnlyMarker ? \"▶ \" : \"─▶ \";\n  line += arrow + marker.explain;\n\n  const colorFn = marker.color ?? identity;\n  return \" \".repeat(midCol) + colorFn(line);\n}\n\n/**\n * @example\n * inline`function ${{text: \"hello\", explain: \"name not allowed bro\"}}() {\\n  return 666\\n}`;\n * =>\n * function hello() {\n *          ──┬──\n *            ╰▶ name not allowed bro\n *   return 666\n * }\n */\nexport function inline(text: TemplateStringsArray, ...values: Explainish[]): string {\n  const resultLines: string[] = [];\n  let currentLine = \"\";\n  let currentLineVisualLen = 0;\n  let pendingMarkers: Marker[] = [];\n\n  const flushLine = () => {\n    resultLines.push(currentLine);\n    if (pendingMarkers.length === 0) {\n      currentLine = \"\";\n      currentLineVisualLen = 0;\n      return;\n    }\n\n    const markerMids = pendingMarkers.map(getMarkerMidpoint);\n\n    resultLines.push(buildUnderline(pendingMarkers));\n\n    for (let i = 0; i < pendingMarkers.length; i++) {\n      const line = buildExplanationLine(\n        pendingMarkers[i],\n        markerMids[i],\n        markerMids.slice(i + 1),\n        pendingMarkers.length === 1,\n      );\n      resultLines.push(line);\n    }\n\n    pendingMarkers = [];\n    currentLine = \"\";\n    currentLineVisualLen = 0;\n  };\n\n  for (let i = 0; i < text.length; i++) {\n    const segment = text[i];\n    const lines = segment.split(\"\\n\");\n\n    for (let j = 0; j < lines.length; j++) {\n      if (j > 0) {\n        flushLine();\n      }\n      currentLine += lines[j];\n      currentLineVisualLen += lines[j].length;\n    }\n\n    if (i < values.length) {\n      const val = values[i];\n      const value: Explain = !Array.isArray(val)\n        ? val\n        : { text: val[0], explain: val[1], ...val[2] };\n      const startCol = currentLineVisualLen;\n      const colorFn = value.color ?? ((s: string) => s);\n      currentLine += colorFn(value.text);\n      currentLineVisualLen += value.text.length;\n      const endCol = currentLineVisualLen;\n      pendingMarkers.push({\n        startCol,\n        endCol,\n        explain: value.explain,\n        color: value.color,\n      });\n    }\n  }\n\n  if (currentLine || pendingMarkers.length > 0) {\n    flushLine();\n  }\n\n  return resultLines.join(\"\\n\");\n}\n"],"names":[],"mappings":"AAAO,iBAAA,IAAA;AACA,iBAAA,IAAA;AACA,iBAAA,IAAA;AACA,iBAAA,IAAA;AACA,iBAAA,KAAA;AACP,UAAA,OAAA;AACA;AACA;AACA;AACA;AACA;AACA,KAAA,UAAA,GAAA,OAAA,0CAAA,IAAA,CAAA,OAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,iBAAA,MAAA,OAAA,oBAAA,aAAA,UAAA;;;;"}

package/dist/index.js

@@ -0,0 +1,146 @@
+import pico from 'picocolors';
+
+const styles = {
+    info: pico.blue,
+    help: pico.cyan,
+    warn: pico.yellow,
+    error: pico.red
+};
+function help(messages) {
+    const message = Array.isArray(messages) ? messages.join("\n") : messages;
+    return styles.help(`${pico.bold("help:")} ${message}`);
+}
+function hint(messages) {
+    const message = Array.isArray(messages) ? messages.join("\n") : messages;
+    return styles.info(`${pico.bold("hint:")} ${message}`);
+}
+function note(messages) {
+    const message = Array.isArray(messages) ? messages.join("\n") : messages;
+    return styles.info(`${pico.bold("note:")} ${message}`);
+}
+function code(str) {
+    return pico.italic(`${pico.dim("`")}${str}${pico.dim("`")}`);
+}
+function frame(text, contents) {
+    const result = [
+        text
+    ];
+    contents.forEach((content, index)=>{
+        const lines = content.split("\n");
+        const isLastContent = index === contents.length - 1;
+        const firstLinePrefix = isLastContent ? "╰▶ " : "├▶ ";
+        const continuationPrefix = isLastContent ? "   " : "│  ";
+        const framedLines = lines.map((line, lineIndex)=>{
+            const prefix = lineIndex === 0 ? firstLinePrefix : continuationPrefix;
+            return `${prefix}${line}`;
+        });
+        result.push(...framedLines);
+    });
+    return result.join("\n");
+}
+const identity = (s)=>s;
+function getMarkerMidpoint(marker) {
+    const textLen = marker.endCol - marker.startCol;
+    return marker.startCol + Math.floor(textLen / 2);
+}
+function buildUnderline(markers) {
+    const parts = [];
+    let pos = 0;
+    for (const marker of markers){
+        const textLen = marker.endCol - marker.startCol;
+        const midPoint = Math.floor(textLen / 2);
+        if (marker.startCol > pos) {
+            parts.push(" ".repeat(marker.startCol - pos));
+            pos = marker.startCol;
+        }
+        const segment = `${"─".repeat(midPoint)}┬${"─".repeat(textLen - midPoint - 1)}`;
+        const colorFn = marker.color ?? identity;
+        parts.push(colorFn(segment));
+        pos += textLen;
+    }
+    return parts.join("");
+}
+function buildExplanationLine(marker, midCol, remainingMids, isOnlyMarker) {
+    let line = "╰";
+    let pos = midCol + 1;
+    for (const nextMid of remainingMids){
+        while(pos < nextMid){
+            line += "─";
+            pos++;
+        }
+        line += "┼";
+        pos++;
+    }
+    const arrow = isOnlyMarker ? "▶ " : "─▶ ";
+    line += arrow + marker.explain;
+    const colorFn = marker.color ?? identity;
+    return " ".repeat(midCol) + colorFn(line);
+}
+/**
+ * @example
+ * inline`function ${{text: "hello", explain: "name not allowed bro"}}() {\n  return 666\n}`;
+ * =>
+ * function hello() {
+ *          ──┬──
+ *            ╰▶ name not allowed bro
+ *   return 666
+ * }
+ */ function inline(text, ...values) {
+    const resultLines = [];
+    let currentLine = "";
+    let currentLineVisualLen = 0;
+    let pendingMarkers = [];
+    const flushLine = ()=>{
+        resultLines.push(currentLine);
+        if (pendingMarkers.length === 0) {
+            currentLine = "";
+            currentLineVisualLen = 0;
+            return;
+        }
+        const markerMids = pendingMarkers.map(getMarkerMidpoint);
+        resultLines.push(buildUnderline(pendingMarkers));
+        for(let i = 0; i < pendingMarkers.length; i++){
+            const line = buildExplanationLine(pendingMarkers[i], markerMids[i], markerMids.slice(i + 1), pendingMarkers.length === 1);
+            resultLines.push(line);
+        }
+        pendingMarkers = [];
+        currentLine = "";
+        currentLineVisualLen = 0;
+    };
+    for(let i = 0; i < text.length; i++){
+        const segment = text[i];
+        const lines = segment.split("\n");
+        for(let j = 0; j < lines.length; j++){
+            if (j > 0) {
+                flushLine();
+            }
+            currentLine += lines[j];
+            currentLineVisualLen += lines[j].length;
+        }
+        if (i < values.length) {
+            const val = values[i];
+            const value = !Array.isArray(val) ? val : {
+                text: val[0],
+                explain: val[1],
+                ...val[2]
+            };
+            const startCol = currentLineVisualLen;
+            const colorFn = value.color ?? ((s)=>s);
+            currentLine += colorFn(value.text);
+            currentLineVisualLen += value.text.length;
+            const endCol = currentLineVisualLen;
+            pendingMarkers.push({
+                startCol,
+                endCol,
+                explain: value.explain,
+                color: value.color
+            });
+        }
+    }
+    if (currentLine || pendingMarkers.length > 0) {
+        flushLine();
+    }
+    return resultLines.join("\n");
+}
+
+export { code, frame, help, hint, inline, note };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "balagan",
+  "version": "0.0.0",
+  "license": "MIT",
+  "author": "Gal Schlezinger",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "dev": "tsdx dev",
+    "build": "tsdx build",
+    "test": "tsdx test",
+    "test:watch": "tsdx test --watch",
+    "lint": "tsdx lint",
+    "format": "tsdx format",
+    "format:check": "tsdx format --check",
+    "typecheck": "tsdx typecheck",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "bunchee": "^6.9.3",
+    "oxfmt": "^0.23.0",
+    "oxlint": "^1.38.0",
+    "picocolors": "^1.1.1",
+    "prettier": "^3.7.4",
+    "vitest": "^4.0.16"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdx": "^2.0.0",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/index.ts

@@ -0,0 +1,196 @@
+import pico from "picocolors";
+
+const styles = {
+  info: pico.blue,
+  help: pico.cyan,
+  warn: pico.yellow,
+  error: pico.red,
+};
+
+export function help(messages: string | string[]) {
+  const message = Array.isArray(messages) ? messages.join("\n") : messages;
+  return styles.help(`${pico.bold("help:")} ${message}`);
+}
+
+export function hint(messages: string | string[]) {
+  const message = Array.isArray(messages) ? messages.join("\n") : messages;
+  return styles.info(`${pico.bold("hint:")} ${message}`);
+}
+
+export function note(messages: string | string[]) {
+  const message = Array.isArray(messages) ? messages.join("\n") : messages;
+  return styles.info(`${pico.bold("note:")} ${message}`);
+}
+
+export function code(str: string) {
+  return pico.italic(`${pico.dim("`")}${str}${pico.dim("`")}`);
+}
+
+export function frame(text: string, contents: string[]): string {
+  const result = [text];
+
+  contents.forEach((content, index) => {
+    const lines = content.split("\n");
+    const isLastContent = index === contents.length - 1;
+
+    const firstLinePrefix = isLastContent ? "╰▶ " : "├▶ ";
+    const continuationPrefix = isLastContent ? "   " : "│  ";
+
+    const framedLines = lines.map((line, lineIndex) => {
+      const prefix = lineIndex === 0 ? firstLinePrefix : continuationPrefix;
+      return `${prefix}${line}`;
+    });
+
+    result.push(...framedLines);
+  });
+
+  return result.join("\n");
+}
+
+interface Explain {
+  text: string;
+  explain: string;
+  /** adds ansi coloring */
+  color?: (s: string) => string;
+}
+
+type Explainish = Explain | [text: string, explain: string, opts?: Pick<Explain, "color">];
+
+type Marker = {
+  startCol: number;
+  endCol: number;
+  explain: string;
+  color?: (s: string) => string;
+};
+
+const identity = (s: string) => s;
+
+function getMarkerMidpoint(marker: Marker): number {
+  const textLen = marker.endCol - marker.startCol;
+  return marker.startCol + Math.floor(textLen / 2);
+}
+
+function buildUnderline(markers: Marker[]): string {
+  const parts: string[] = [];
+  let pos = 0;
+  for (const marker of markers) {
+    const textLen = marker.endCol - marker.startCol;
+    const midPoint = Math.floor(textLen / 2);
+
+    if (marker.startCol > pos) {
+      parts.push(" ".repeat(marker.startCol - pos));
+      pos = marker.startCol;
+    }
+    const segment = `${"─".repeat(midPoint)}┬${"─".repeat(textLen - midPoint - 1)}`;
+    const colorFn = marker.color ?? identity;
+    parts.push(colorFn(segment));
+    pos += textLen;
+  }
+  return parts.join("");
+}
+
+function buildExplanationLine(
+  marker: Marker,
+  midCol: number,
+  remainingMids: number[],
+  isOnlyMarker: boolean,
+): string {
+  let line = "╰";
+  let pos = midCol + 1;
+
+  for (const nextMid of remainingMids) {
+    while (pos < nextMid) {
+      line += "─";
+      pos++;
+    }
+    line += "┼";
+    pos++;
+  }
+
+  const arrow = isOnlyMarker ? "▶ " : "─▶ ";
+  line += arrow + marker.explain;
+
+  const colorFn = marker.color ?? identity;
+  return " ".repeat(midCol) + colorFn(line);
+}
+
+/**
+ * @example
+ * inline`function ${{text: "hello", explain: "name not allowed bro"}}() {\n  return 666\n}`;
+ * =>
+ * function hello() {
+ *          ──┬──
+ *            ╰▶ name not allowed bro
+ *   return 666
+ * }
+ */
+export function inline(text: TemplateStringsArray, ...values: Explainish[]): string {
+  const resultLines: string[] = [];
+  let currentLine = "";
+  let currentLineVisualLen = 0;
+  let pendingMarkers: Marker[] = [];
+
+  const flushLine = () => {
+    resultLines.push(currentLine);
+    if (pendingMarkers.length === 0) {
+      currentLine = "";
+      currentLineVisualLen = 0;
+      return;
+    }
+
+    const markerMids = pendingMarkers.map(getMarkerMidpoint);
+
+    resultLines.push(buildUnderline(pendingMarkers));
+
+    for (let i = 0; i < pendingMarkers.length; i++) {
+      const line = buildExplanationLine(
+        pendingMarkers[i],
+        markerMids[i],
+        markerMids.slice(i + 1),
+        pendingMarkers.length === 1,
+      );
+      resultLines.push(line);
+    }
+
+    pendingMarkers = [];
+    currentLine = "";
+    currentLineVisualLen = 0;
+  };
+
+  for (let i = 0; i < text.length; i++) {
+    const segment = text[i];
+    const lines = segment.split("\n");
+
+    for (let j = 0; j < lines.length; j++) {
+      if (j > 0) {
+        flushLine();
+      }
+      currentLine += lines[j];
+      currentLineVisualLen += lines[j].length;
+    }
+
+    if (i < values.length) {
+      const val = values[i];
+      const value: Explain = !Array.isArray(val)
+        ? val
+        : { text: val[0], explain: val[1], ...val[2] };
+      const startCol = currentLineVisualLen;
+      const colorFn = value.color ?? ((s: string) => s);
+      currentLine += colorFn(value.text);
+      currentLineVisualLen += value.text.length;
+      const endCol = currentLineVisualLen;
+      pendingMarkers.push({
+        startCol,
+        endCol,
+        explain: value.explain,
+        color: value.color,
+      });
+    }
+  }
+
+  if (currentLine || pendingMarkers.length > 0) {
+    flushLine();
+  }
+
+  return resultLines.join("\n");
+}