inkplot-scratch 0.0.1-placeholder.0 → 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neofox Solutions LLP and Hamish Milne
+
+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

@@ -1,3 +1,61 @@
-# inkplot-scratch
+---
+name: inkplot-data-charts
+description: Use when the user wants charts, plots or visualisations of their data (Excel, CSV, JSON) as an interactive HTML page, as SVG/PNG figures, or as figures inside a Word, PowerPoint or PDF report. Builds them with the inkplot npm package and a checking command.
+---
 
-This is a placeholder. See https://github.com/neofox-solutions/inkplot for the real package.
+# Charts from data with inkplot
+
+You write one TypeScript module that exports the charts; `inkplot-scratch` type-checks it, draws it, and writes an interactive HTML page, SVG files, PNG files or JSON facts. Reading the spreadsheet and building the Word/PowerPoint/PDF file are other skills' jobs: use them.
+
+## 1. Set up (once per workspace; skip if `inkplot-scratch/` exists)
+
+```sh
+mkdir -p inkplot-scratch && cd inkplot-scratch && npm init -y >/dev/null && npm i inkplot inkplot-scratch
+```
+
+Run everything below from that folder. If `npm i` cannot reach the registry, say so and stop: do not hand-write SVG.
+
+Then read `node_modules/inkplot-scratch/skill/inkplot/SKILL.md` (rules, template, attributes of the common elements). Its examples are plain TypeScript, `new Element(attributes, ...children)`, which is how you write charts here. Its **Topics** index names a file in `…/skill/inkplot/topics/` for each kind of chart (histograms, box plots, polar, heat maps, axes, time…): open only the one or two you need.
+
+## 2. Look at the data before charting
+
+Print the sheet names, column names, types, ranges and row count. Decide which columns the request means (units too: an angle may be degrees or radians) and say your assumptions in the reply; ask only if a wrong guess would mislead. Write the rows to `inkplot-scratch/data.json`, next to `source.ts` (an array of objects; numbers as numbers, times as epoch milliseconds or ISO strings). The module imports it, so the page is self-contained and every re-run uses the same data.
+
+## 3. Write `source.ts`
+
+It differs from the template in the inkplot skill in one way: instead of printing the SVG with `toSvgString`/`console.log`, the file ends with the charts:
+
+```ts
+import rows from './data.json';
+// … imports from 'inkplot' …
+const histogram = () => new Chart({ theme: lightTheme, meta: { title: 'Magnitude histogram' } }, /* plane, axes, series */);
+export default [histogram(), { name: 'Box by second', caption: 'Quartiles per 1 s bucket', chart: box() }];
+```
+
+- Each item is a chart or `{ chart, name?, caption?, interactive? }`; the name (else `meta.title`, else "Figure N") becomes the figure title and file name.
+- One chart object per figure: a chart used twice, or one element shared between charts, is an error. Make charts with functions.
+- Reshaping the request names (bins, buckets, filters) can be done right in the module on `rows`.
+- "Axis starts at 0" is `min: 0` on that axis (a histogram's axis otherwise starts at its first bin centre).
+- `tsc` checks every `new` call: attribute names and types, and which children each element takes, in what order. Read its message for the element named in it.
+
+## 4. Run, read, fix
+
+```sh
+npx inkplot-scratch source.ts --check
+```
+
+- Type errors print to stderr exactly as `tsc` prints them; runtime errors name the line in `source.ts`. Fix and run again; nothing is written until it type-checks. (`.tsx` with JSX also works, but TypeScript does not check JSX children.)
+- On success it prints, per figure: series and point counts, the **real range of each axis** and its ticks, and `WARNING` lines (empty series, NaN). Compare this with the request: "x starts at 0" must read `range 0 to …`; a bin width shows in the ticks and bar count. Fix before you deliver.
+- `--check` cannot see overlapping labels, clipped text or crowded keys. After it passes, run `--png` once and open the PNG of each figure (the image viewer, not the facts) and fix what you see: shorten category labels, use fewer ticks, widen the chart. Label overlap is the usual one.
+
+Outputs (combine freely, `--check` runs with all of them; paths are relative to where you run it): `--html page.html`, `--svg dir`, `--png dir` (2x, white background, fonts bundled; files are named `01-<figure name>.svg`, in order), `--json facts.json` (what `--check` prints: point counts and axis ranges, not statistics), `--title "Page title"` for the page (default: the file name). Charts are 640x400 unless the chart sets `width`/`height` or you pass `--width/--height`.
+
+## 5. Deliver
+
+- **Interactive:** `--html` gives one self-contained file: every chart live, with Copy/Download for SVG and PNG, a Stats panel, download-all, and pan/zoom, Shift-drag zoom box, crosshair and tooltip added for you (don't add these yourself; `--static` or `interactive: false` on an item turns them off). Give the person that file.
+- **In a document:** write the numbers in the prose by computing them from the data in code (counts, means, quartiles, per-bin counts), or from `--json` for axis ranges and point counts, never by reading the picture. Embed the figures with the Word/PowerPoint/PDF skill. Word takes SVG natively, but docx-js insists on a PNG fallback beside it: run `--svg figs --png figs` and use the pair, `new ImageRun({ type: 'svg', data: svg, fallback: { type: 'png', data: png }, transformation: { width, height } })`, with `data` read as a Buffer (`readFileSync` with no encoding; a string is taken as base64). For anything else use the PNG. A figure's `caption` shows on the HTML page only: write captions into the document yourself.
+- **Changes:** edit `source.ts`, run all the outputs again, re-embed. Keep `source.ts` and `data.json` so the next request starts from them.
+
+## Know the limits
+
+The page exports a chart as written, not as zoomed (the added interactions never reach the SVG or PNG files). Clipboard buttons need browser permission and fall back to a download. SVG text uses the viewer's `system-ui` font; PNGs use the bundled Inter.

package/bin.mjs

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// scratch/src/png.ts
+var png_exports = {};
+__export(png_exports, {
+  renderer: () => renderer
+});
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+async function renderer(workspace2, background, scale) {
+  let resvg, wasm;
+  try {
+    const need = createRequire(join(workspace2, "x.js"));
+    resvg = await load(need.resolve("@resvg/resvg-wasm"));
+    wasm = need.resolve("@resvg/resvg-wasm/index_bg.wasm");
+  } catch {
+    try {
+      const own = createRequire(import.meta.url);
+      resvg = await load(own.resolve("@resvg/resvg-wasm"));
+      wasm = own.resolve("@resvg/resvg-wasm/index_bg.wasm");
+    } catch {
+      process.stderr.write("error: --png needs @resvg/resvg-wasm. Run: npm i @resvg/resvg-wasm\n");
+      return process.exit(1);
+    }
+  }
+  await resvg.initWasm(readFileSync(wasm));
+  const here2 = dirname(fileURLToPath(import.meta.url)), fonts = [join(here2, "../fonts"), join(here2, "fonts")].find((d) => {
+    try {
+      readFileSync(join(d, "Inter-Regular.otf"));
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  const fontBuffers = fonts ? ["Inter-Regular.otf", "Inter-Bold.otf"].map((f) => new Uint8Array(readFileSync(join(fonts, f)))) : [];
+  return (svg) => new resvg.Resvg(svg, {
+    ...background !== "none" && { background: background ?? "#ffffff" },
+    fitTo: { mode: "zoom", value: scale },
+    font: { fontBuffers, defaultFontFamily: "Inter", loadSystemFonts: false }
+  }).render().asPng();
+}
+var load;
+var init_png = __esm({
+  "scratch/src/png.ts"() {
+    "use strict";
+    load = async (path) => {
+      const m = await import(pathToFileURL(path).href);
+      return "initWasm" in m ? m : m.default;
+    };
+  }
+});
+
+// scratch/src/cli.ts
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync as readFileSync2, rmSync, statSync, writeFileSync } from "node:fs";
+import { createRequire as createRequire2 } from "node:module";
+import { tmpdir } from "node:os";
+import { basename, dirname as dirname2, extname, join as join2, relative, resolve } from "node:path";
+import { fileURLToPath as fileURLToPath2, pathToFileURL as pathToFileURL2 } from "node:url";
+import { build, formatMessages } from "esbuild";
+var USAGE = `inkplot-scratch <source.ts|tsx> [options]
+
+  The source module ends with:  export default [chart1, chart2];
+  (an item may also be { chart, name?, caption? }; a lone chart is one figure)
+
+  --check            type-check, render every chart, and print what each holds (the default when no output is asked for)
+  --svg <dir>        one SVG file per chart:  01-histogram.svg, 02-box.svg, \u2026
+  --png <dir>        one PNG file per chart (needs @resvg/resvg-wasm; fonts are bundled)
+  --html <file>      one self-contained interactive page with every chart, copy/download buttons and stats
+  --json <file|->    the facts as JSON (series, point counts, axis ranges, warnings), for writing prose from
+  --width <px> --height <px>   size for charts that do not set their own (default 640 by 400)
+  --scale <n>        PNG pixels per CSS pixel (default 2)
+  --background <css> PNG background (default white; "none" for transparent)
+  --title <text>     page title for --html (default: the file name)
+  --static           --html without the added pan/zoom, crosshair and tooltip (a figure can opt out with interactive: false)
+  --no-typecheck     skip tsc (not recommended)
+
+Type errors print to stderr exactly as \`tsc\` prints them; exit status 1 means fix the source and run again.`;
+function fail(text, code = 1) {
+  process.stderr.write(text.endsWith("\n") ? text : text + "\n");
+  return process.exit(code);
+}
+var flags = /* @__PURE__ */ new Set(["--check", "--no-typecheck", "--static"]);
+var valued = /* @__PURE__ */ new Set(["--svg", "--png", "--html", "--json", "--width", "--height", "--scale", "--background", "--title"]);
+var on = /* @__PURE__ */ new Set();
+var values = /* @__PURE__ */ new Map();
+var positional = [];
+for (let i = 2; i < process.argv.length; i++) {
+  const a = process.argv[i];
+  if (a === "-h" || a === "--help") {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  if (flags.has(a)) on.add(a);
+  else if (valued.has(a)) {
+    const v = process.argv[++i];
+    if (v === void 0) fail(`${a} needs a value
+
+${USAGE}`, 2);
+    values.set(a, v);
+  } else if (a.startsWith("--")) fail(`unknown option ${a}
+
+${USAGE}`, 2);
+  else positional.push(a);
+}
+var sourceArg = positional[0];
+if (positional.length !== 1 || !sourceArg) fail(`give exactly one source file
+
+${USAGE}`, 2);
+var num = (name) => {
+  const v = values.get(name);
+  if (v === void 0) return void 0;
+  const n = Number(v);
+  if (!(n > 0) || !Number.isFinite(n)) fail(`${name} must be a number above 0, not "${v}"`, 2);
+  return n;
+};
+var width = num("--width");
+var height = num("--height");
+var size = { ...width && { width }, ...height && { height } };
+var source = resolve(sourceArg);
+var workspace = process.cwd();
+if (!existsSync(source)) fail(`no such file: ${sourceArg}`, 2);
+var wantsOutput = ["--svg", "--png", "--html", "--json"].some((k) => values.has(k));
+var check = on.has("--check") || !wantsOutput;
+var here = dirname2(fileURLToPath2(import.meta.url));
+var assets = existsSync(join2(here, "figures.ts")) ? here : join2(here, "src");
+if (!on.has("--no-typecheck")) {
+  const find = (from) => {
+    try {
+      const json = createRequire2(from).resolve("typescript/package.json");
+      return join2(dirname2(json), JSON.parse(readFileSync2(json, "utf8")).bin.tsc);
+    } catch {
+      return null;
+    }
+  };
+  const tsc = find(join2(workspace, "x.js")) ?? find(import.meta.url) ?? fail("typescript is not installed here. Run: npm i inkplot-scratch typescript");
+  const r = spawnSync(process.execPath, [
+    tsc,
+    "--noEmit",
+    "--pretty",
+    "false",
+    "--strict",
+    "--noUncheckedIndexedAccess",
+    "--target",
+    "es2022",
+    "--module",
+    "esnext",
+    "--moduleResolution",
+    "bundler",
+    "--lib",
+    "es2022,dom",
+    "--jsx",
+    "react-jsx",
+    "--jsxImportSource",
+    "inkplot",
+    "--resolveJsonModule",
+    "--allowImportingTsExtensions",
+    "--skipLibCheck",
+    "--esModuleInterop",
+    source
+  ], { cwd: workspace, encoding: "utf8" });
+  if (r.status !== 0) {
+    const said = (r.stdout + r.stderr).trim();
+    fail(said + (/error TS\d+/.test(said) ? "" : "\n\nThis is tsc failing to run, not a problem in your source. If it names a missing @typescript/\u2026 package, the install skipped optional dependencies: run npm i again without --omit=optional. To go on without type-checking, add --no-typecheck.") + "\n");
+  }
+}
+var oneInkplot = () => ({
+  name: "one-inkplot",
+  setup(b) {
+    b.onResolve({ filter: /^inkplot(\/|$)/ }, async (args) => {
+      if (args.pluginData === "inkplot") return void 0;
+      const r = await b.resolve(args.path, { resolveDir: workspace, kind: args.kind, pluginData: "inkplot" });
+      return r.errors.length ? { errors: [{ text: `cannot find "${args.path}" from ${workspace}. Run: npm i inkplot` }] } : { path: r.path };
+    });
+  }
+});
+var common = {
+  bundle: true,
+  write: false,
+  jsx: "automatic",
+  jsxImportSource: "inkplot",
+  plugins: [oneInkplot()],
+  logLevel: "silent",
+  target: "es2022",
+  loader: { ".csv": "text", ".tsv": "text", ".txt": "text" },
+  absWorkingDir: workspace
+};
+var bundle = async (extra, entry) => {
+  try {
+    const out = await build({ ...common, ...extra, stdin: { contents: entry, resolveDir: dirname2(source), loader: "ts", sourcefile: "inkplot-scratch-entry.ts" } });
+    return out.outputFiles?.[0]?.text ?? fail("esbuild produced no output");
+  } catch (e) {
+    const errors = e.errors;
+    if (!errors) throw e;
+    return fail((await formatMessages(errors, { kind: "error", color: false, terminalWidth: 100 })).join("\n"));
+  }
+};
+var q = JSON.stringify;
+var tmp = mkdtempSync(join2(tmpdir(), "inkplot-scratch-"));
+process.on("exit", () => rmSync(tmp, { recursive: true, force: true }));
+var nodeCode = await bundle(
+  { platform: "node", format: "esm", sourcemap: "inline", sourcesContent: false },
+  `import * as user from ${q(source)};
+import { checkText, figuresOf, factsOf, svgOf } from ${q(join2(assets, "figures.ts"))};
+export { checkText, factsOf, svgOf };
+export const figures = figuresOf(user);
+`
+);
+var file = join2(tmp, "run.mjs");
+writeFileSync(file, nodeCode);
+process.setSourceMapsEnabled(true);
+var describeThrown = (e) => e instanceof Error ? { message: e.message, stack: e.stack ?? "" } : { message: String(e), stack: "" };
+var run;
+try {
+  run = await import(pathToFileURL2(file).href);
+} catch (e) {
+  const err = describeThrown(e);
+  const all = err.stack.split("\n").slice(1).filter((l) => !l.includes("node:internal") && !l.includes("bin.mjs"));
+  const mine = all.filter((l) => l.includes(dirname2(source)) && !l.includes("node_modules"));
+  fail(`error: ${err.message}
+${(mine.length ? mine : all).slice(0, 6).join("\n")}
+`);
+}
+var kb = (path) => `${(statSync(path).size / 1024).toFixed(1)} KB`;
+var shown = (path) => relative(workspace, path) || path;
+var figures = run.figures;
+var svgs;
+var facts;
+try {
+  facts = figures.map((f) => run.factsOf(f, size));
+  svgs = figures.map((f) => run.svgOf(f, size));
+} catch (e) {
+  const err = describeThrown(e);
+  fail(`error while drawing: ${err.message}
+${err.stack.split("\n").slice(1).filter((l) => l.includes(source)).slice(0, 4).join("\n")}
+`);
+}
+if (check) for (const f of facts) console.log(run.checkText(f));
+var dir = (path) => {
+  const d = resolve(path);
+  mkdirSync(d, { recursive: true });
+  return d;
+};
+var written = [];
+var svgDir = values.get("--svg");
+var pngDir = values.get("--png");
+var jsonPath = values.get("--json");
+var htmlPath = values.get("--html");
+if (svgDir !== void 0) {
+  const d = dir(svgDir);
+  figures.forEach((f, i) => {
+    const p = join2(d, `${f.id}.svg`);
+    writeFileSync(p, svgs[i]);
+    written.push(`${shown(p)} (${kb(p)})`);
+  });
+}
+if (pngDir !== void 0) {
+  const d = dir(pngDir);
+  const { renderer: renderer2 } = await Promise.resolve().then(() => (init_png(), png_exports));
+  const draw = await renderer2(workspace, values.get("--background"), num("--scale") ?? 2);
+  figures.forEach((f, i) => {
+    const p = join2(d, `${f.id}.png`);
+    writeFileSync(p, draw(svgs[i]));
+    written.push(`${shown(p)} (${kb(p)})`);
+  });
+}
+if (jsonPath !== void 0) {
+  const text = JSON.stringify(facts, null, 2) + "\n";
+  if (jsonPath === "-") process.stdout.write(text);
+  else {
+    const p = resolve(jsonPath);
+    mkdirSync(dirname2(p), { recursive: true });
+    writeFileSync(p, text);
+    written.push(`${shown(p)} (${kb(p)})`);
+  }
+}
+if (htmlPath !== void 0) {
+  const title = values.get("--title") ?? basename(source, extname(source));
+  const script = await bundle(
+    { platform: "browser", format: "iife", minifyWhitespace: true, minifySyntax: true },
+    `import * as user from ${q(source)};
+import { mount } from ${q(join2(assets, "app.ts"))};
+mount(user, ${q(title)}, { interactive: ${on.has("--static") ? "false" : "true"} });
+`
+  );
+  const template = readFileSync2(join2(assets, "template.html"), "utf8");
+  const html = template.replace("/*SCRIPT*/", () => script.replace(/<\/(script)/gi, "<\\/$1")).replace("<title>Charts</title>", () => `<title>${title.replace(/[&<>]/g, (c) => `&#${c.charCodeAt(0)};`)}</title>`);
+  const p = resolve(htmlPath);
+  mkdirSync(dirname2(p), { recursive: true });
+  writeFileSync(p, html);
+  written.push(`${shown(p)} (${kb(p)})`);
+}
+for (const w of written) (jsonPath === "-" ? process.stderr : process.stdout).write(`wrote ${w}
+`);
+for (const f of facts) for (const p of f.problems) process.stderr.write(`warning: ${f.id}: ${p}
+`);

package/fonts/LICENSE.txt

@@ -0,0 +1,133 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: fonts-inter
+Upstream-Contact: The Inter Project Authors <rasmus@notion.se>
+Source: https://github.com/rsms/inter
+Files-Excluded: docs/font-files/*.woff* docs/lab docs/samples
+
+Files: *
+Copyright: 2016-2023 The Inter Project Authors <rasmus@notion.se>
+License: OFL-1.1 and Apache-2.0
+
+License: OFL-1.1
+ PREAMBLE
+ The goals of the Open Font License (OFL) are to stimulate worldwide
+ development of collaborative font projects, to support the font
+ creation efforts of academic and linguistic communities, and to
+ provide a free and open framework in which fonts may be shared and
+ improved in partnership with others.
+ .
+ The OFL allows the licensed fonts to be used, studied, modified and
+ redistributed freely as long as they are not sold by themselves. The
+ fonts, including any derivative works, can be bundled, embedded,
+ redistributed and/or sold with any software provided that any
+ reserved names are not used by derivative works. The fonts and
+ derivatives, however, cannot be released under any other type of
+ license. The requirement for fonts to remain under this license
+ does not apply to any document created using the fonts or their
+ derivatives.
+ .
+ DEFINITIONS
+ Font Software refers to the set of files released by the
+ Copyright Holder(s) under this license and clearly marked as such.
+ This may include source files, build scripts and documentation.
+ .
+ Reserved Font Name refers to any names specified as such after
+ the copyright statement(s).
+ .
+ Original Version refers to the collection of Font Software
+ components as distributed by the Copyright Holder(s).
+ .
+ Modified Version refers to any derivative made by adding to,
+ deleting, or substituting in part or in whole any of the components
+ of the Original Version, by changing formats or by porting the Font
+ Software to a new environment.
+ .
+ Author refers to any designer, engineer, programmer, technical
+ writer or other person who contributed to the Font Software.
+ .
+ PERMISSION & CONDITIONS
+ Permission is hereby granted, free of charge, to any person
+ obtaining a copy of the Font Software, to use, study, copy, merge,
+ embed, modify, redistribute, and sell modified and unmodified copies
+ of the Font Software, subject to the following conditions:
+ .
+ 1) Neither the Font Software nor any of its individual components,
+    in Original or Modified Versions, may be sold by itself.
+ .
+ 2) Original or Modified Versions of the Font Software may be bundled,
+    redistributed and/or sold with any software, provided that each
+    copy contains the above copyright notice and this license. These
+    can be included either as stand-alone text files, human-readable
+    headers or in the appropriate machine-readable metadata fields
+    within text or binary files as long as those fields can be easily
+    viewed by the user.
+ .
+ 3) No Modified Version of the Font Software may use the Reserved Font
+    Name(s) unless explicit written permission is granted by the
+    corresponding Copyright Holder. This restriction only applies to
+    the primary font name as presented to the users.
+ .
+ 4) The name(s) of the Copyright Holder(s) or the Author(s) of the
+    Font Software shall not be used to promote, endorse or advertise
+    any Modified Version, except to acknowledge the contribution(s)
+    of the Copyright Holder(s) and the Author(s) or with their
+    explicit written permission.
+ .
+ 5) The Font Software, modified or unmodified, in part or in whole,
+    must be distributed entirely under this license, and must not be
+    distributed under any other license. The requirement for fonts to
+    remain under this license does not apply to any document created
+    using the Font Software.
+ .
+ TERMINATION
+ This license becomes null and void if any of the above conditions
+ are not met.
+ .
+ DISCLAIMER
+ THE FONT SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+ OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL
+ THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR
+ CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE THE FONT
+ SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.
+
+License: Apache-2.0
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+ .
+      https://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ .
+ On Debian systems, the full text of the Apache Software License version 2 can
+ be found in the file `/usr/share/common-licenses/Apache-2.0'.
+
+Files: debian/*
+Copyright: 2019-2023 Gürkan Myczko <tar@debian.org>
+License: GPL-2+
+ This package is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+ .
+ This package is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+ .
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see <https://www.gnu.org/licenses/>
+ .
+ On Debian systems, the complete text of the GNU General
+ Public License version 2 can be found in "/usr/share/common-licenses/GPL-2".

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "inkplot-scratch",
-  "version": "0.0.1-placeholder.0",
-  "description": "Placeholder for inkplot-scratch; the real releases are published from CI.",
+  "version": "1.0.0-beta.1",
+  "description": "Turn a module that exports inkplot charts into SVG, PNG, JSON facts or a single-file interactive HTML page.",
+  "type": "module",
+  "bin": { "inkplot-scratch": "./bin.mjs" },
+  "files": ["bin.mjs", "src", "fonts", "skill", "README.md"],
+  "dependencies": { "inkplot": "1.0.0-beta.1", "typescript": "^7.0.2", "esbuild": "^0.28.2" },
+  "optionalDependencies": { "@resvg/resvg-wasm": "^2.6.2" },
+  "engines": { "node": ">=22" },
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/neofox-solutions/inkplot.git"
-  },
-  "homepage": "https://github.com/neofox-solutions/inkplot#readme"
-}
+  "repository": { "type": "git", "url": "git+https://github.com/neofox-solutions/inkplot.git", "directory": "scratch" },
+  "homepage": "https://github.com/neofox-solutions/inkplot/tree/main/scratch#readme",
+  "bugs": { "url": "https://github.com/neofox-solutions/inkplot/issues" },
+  "keywords": ["chart", "svg", "png", "cli", "inkplot"]
+}

package/skill/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: inkplot-data-charts
+description: Use when the user wants charts, plots or visualisations of their data (Excel, CSV, JSON) as an interactive HTML page, as SVG/PNG figures, or as figures inside a Word, PowerPoint or PDF report. Builds them with the inkplot npm package and a checking command.
+---
+
+# Charts from data with inkplot
+
+You write one TypeScript module that exports the charts; `inkplot-scratch` type-checks it, draws it, and writes an interactive HTML page, SVG files, PNG files or JSON facts. Reading the spreadsheet and building the Word/PowerPoint/PDF file are other skills' jobs: use them.
+
+## 1. Set up (once per workspace; skip if `inkplot-scratch/` exists)
+
+```sh
+mkdir -p inkplot-scratch && cd inkplot-scratch && npm init -y >/dev/null && npm i inkplot inkplot-scratch
+```
+
+Run everything below from that folder. If `npm i` cannot reach the registry, say so and stop: do not hand-write SVG.
+
+Then read `node_modules/inkplot-scratch/skill/inkplot/SKILL.md` (rules, template, attributes of the common elements). Its examples are plain TypeScript, `new Element(attributes, ...children)`, which is how you write charts here. Its **Topics** index names a file in `…/skill/inkplot/topics/` for each kind of chart (histograms, box plots, polar, heat maps, axes, time…): open only the one or two you need.
+
+## 2. Look at the data before charting
+
+Print the sheet names, column names, types, ranges and row count. Decide which columns the request means (units too: an angle may be degrees or radians) and say your assumptions in the reply; ask only if a wrong guess would mislead. Write the rows to `inkplot-scratch/data.json`, next to `source.ts` (an array of objects; numbers as numbers, times as epoch milliseconds or ISO strings). The module imports it, so the page is self-contained and every re-run uses the same data.
+
+## 3. Write `source.ts`
+
+It differs from the template in the inkplot skill in one way: instead of printing the SVG with `toSvgString`/`console.log`, the file ends with the charts:
+
+```ts
+import rows from './data.json';
+// … imports from 'inkplot' …
+const histogram = () => new Chart({ theme: lightTheme, meta: { title: 'Magnitude histogram' } }, /* plane, axes, series */);
+export default [histogram(), { name: 'Box by second', caption: 'Quartiles per 1 s bucket', chart: box() }];
+```
+
+- Each item is a chart or `{ chart, name?, caption?, interactive? }`; the name (else `meta.title`, else "Figure N") becomes the figure title and file name.
+- One chart object per figure: a chart used twice, or one element shared between charts, is an error. Make charts with functions.
+- Reshaping the request names (bins, buckets, filters) can be done right in the module on `rows`.
+- "Axis starts at 0" is `min: 0` on that axis (a histogram's axis otherwise starts at its first bin centre).
+- `tsc` checks every `new` call: attribute names and types, and which children each element takes, in what order. Read its message for the element named in it.
+
+## 4. Run, read, fix
+
+```sh
+npx inkplot-scratch source.ts --check
+```
+
+- Type errors print to stderr exactly as `tsc` prints them; runtime errors name the line in `source.ts`. Fix and run again; nothing is written until it type-checks. (`.tsx` with JSX also works, but TypeScript does not check JSX children.)
+- On success it prints, per figure: series and point counts, the **real range of each axis** and its ticks, and `WARNING` lines (empty series, NaN). Compare this with the request: "x starts at 0" must read `range 0 to …`; a bin width shows in the ticks and bar count. Fix before you deliver.
+- `--check` cannot see overlapping labels, clipped text or crowded keys. After it passes, run `--png` once and open the PNG of each figure (the image viewer, not the facts) and fix what you see: shorten category labels, use fewer ticks, widen the chart. Label overlap is the usual one.
+
+Outputs (combine freely, `--check` runs with all of them; paths are relative to where you run it): `--html page.html`, `--svg dir`, `--png dir` (2x, white background, fonts bundled; files are named `01-<figure name>.svg`, in order), `--json facts.json` (what `--check` prints: point counts and axis ranges, not statistics), `--title "Page title"` for the page (default: the file name). Charts are 640x400 unless the chart sets `width`/`height` or you pass `--width/--height`.
+
+## 5. Deliver
+
+- **Interactive:** `--html` gives one self-contained file: every chart live, with Copy/Download for SVG and PNG, a Stats panel, download-all, and pan/zoom, Shift-drag zoom box, crosshair and tooltip added for you (don't add these yourself; `--static` or `interactive: false` on an item turns them off). Give the person that file.
+- **In a document:** write the numbers in the prose by computing them from the data in code (counts, means, quartiles, per-bin counts), or from `--json` for axis ranges and point counts, never by reading the picture. Embed the figures with the Word/PowerPoint/PDF skill. Word takes SVG natively, but docx-js insists on a PNG fallback beside it: run `--svg figs --png figs` and use the pair, `new ImageRun({ type: 'svg', data: svg, fallback: { type: 'png', data: png }, transformation: { width, height } })`, with `data` read as a Buffer (`readFileSync` with no encoding; a string is taken as base64). For anything else use the PNG. A figure's `caption` shows on the HTML page only: write captions into the document yourself.
+- **Changes:** edit `source.ts`, run all the outputs again, re-embed. Keep `source.ts` and `data.json` so the next request starts from them.
+
+## Know the limits
+
+The page exports a chart as written, not as zoomed (the added interactions never reach the SVG or PNG files). Clipboard buttons need browser permission and fall back to a download. SVG text uses the viewer's `system-ui` font; PNGs use the bundled Inter.