waterplane 0.0.1 → 0.1.6

package/node_modules/@waterplane/shared/dist/collage.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Several pictures as ONE picture — the geometry half.
+ *
+ * The reason this exists is marking, not tidiness. A bug that spans three
+ * screens (tap here, then this list, then this error) can only be circled
+ * across all three if all three are on one canvas: the annotator marks one
+ * image at a time, and an arrow cannot leave it. Sending three separately means
+ * describing the link between them in words, which is the thing a screenshot
+ * was supposed to replace.
+ *
+ * Pure, and here rather than in `web/` for the usual reason: the arrangement is
+ * the part that can be wrong (a column of phone screenshots is a 1:8 ribbon
+ * nobody can read on a phone), and pinning it needs `node --test`, not a
+ * browser. The pixels are pushed in `web/src/collage.ts`.
+ *
+ * Two rules carry the feature:
+ *
+ *  - **Rows normalize on HEIGHT, columns on nothing.** Each row scales its
+ *    images to a common height, so panels sit on a shared baseline and no
+ *    letterbox is needed in the direction that matters. Rows are then centered
+ *    inside the widest row, which is the only place slack can appear.
+ *  - **`pickCols` optimizes the resulting ASPECT, not the count.** Two portrait
+ *    screenshots side by side are ~0.9:1 and read perfectly; stacked they are
+ *    0.23:1, i.e. a ribbon that is 200 px wide by the time it fits a phone —
+ *    the marks on it would be unclickable. The same rule stacks landscape
+ *    captures, for the same reason in the other direction. That is the
+ *    "clever automatism": one number (`COLLAGE_TARGET_ASPECT`) and a search
+ *    over every column count, never a per-orientation special case.
+ */
+/** Natural size of one source image. */
+export interface ImageSize {
+    w: number;
+    h: number;
+}
+/** Where one image lands on the combined canvas, in output pixels. */
+export interface CollageCell {
+    /** Index into the input array — the panel's number, and its draw order. */
+    i: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface CollageLayout {
+    cols: number;
+    rows: number;
+    gap: number;
+    width: number;
+    height: number;
+    /** Global downscale applied to keep the canvas inside the caps. 1 = native. */
+    scale: number;
+    cells: CollageCell[];
+}
+export interface CollageOpts {
+    /** Images per row. Omitted ⇒ `pickCols` decides. */
+    cols?: number;
+    /** Space between panels, in native pixels. Omitted ⇒ `defaultGap`. */
+    gap?: number;
+    maxSide?: number;
+    /**
+     * Cap on WIDTH alone, separate from `maxSide`.
+     *
+     * The combined image is re-encoded to a width before it is uploaded
+     * (`uploadScale.ts`), so drawing it wider than that is bytes and memory spent
+     * on pixels nothing will ever see — and on a phone that is exactly where the
+     * final `toBlob` fails. Capping the SIDE would be wrong for the same job: a
+     * stacked collage is legitimately 1200 × 6000, and the upload rule would keep
+     * every one of those rows.
+     */
+    maxWidth?: number;
+    maxPixels?: number;
+    targetAspect?: number;
+}
+/**
+ * The shape the automatic pick aims at: slightly wider than tall.
+ *
+ * Not 1:1 and not 16:9. Square would put four phone screenshots in a 2×2 grid
+ * (right) but also three of them in a 2+1 grid with a hole in it (wrong — they
+ * are a sequence and read left to right). Anything wide enough to fix that
+ * would put four in a row, at which point each panel is a quarter of the phone
+ * wide. 1.25 is the value that gets both cases right, and the picker is one tap
+ * away for the case it doesn't.
+ */
+export declare const COLLAGE_TARGET_ASPECT = 1.25;
+/** Canvas caps. A phone re-encodes this before upload anyway (`uploadScale.ts`);
+ *  these exist so the CANVAS itself can be allocated on a mid-range device. */
+export declare const COLLAGE_MAX_SIDE = 4096;
+export declare const COLLAGE_MAX_PIXELS = 24000000;
+/**
+ * The gap between panels, derived from the images rather than fixed.
+ *
+ * A 12 px seam is a clear divider between two 400 px thumbnails and invisible
+ * between two 4K screenshots — and the second is the case this feature is for.
+ * Scaling it with the mean panel size keeps "these are two pictures" readable
+ * at every source resolution.
+ */
+export declare function defaultGap(sizes: ImageSize[]): number;
+/**
+ * How many images per row, judged only by the shape that comes out.
+ *
+ * Score is the log-distance from the target aspect, so 2× too wide and 2× too
+ * tall cost the same — a plain ratio would quietly prefer wide ribbons. The
+ * small raggedness penalty is the tie-break: with equal shapes on offer, the
+ * grid that leaves no hole wins.
+ */
+export declare function pickCols(sizes: ImageSize[], gap?: number, targetAspect?: number): number;
+/**
+ * The full arrangement, capped to something a phone can actually allocate.
+ *
+ * Rounding happens once, at the end, on already-scaled numbers: rounding the
+ * native geometry first and scaling the rounded values afterwards drifts the
+ * seams by a pixel per row, which is visible as a wobbling gap.
+ */
+export declare function layoutCollage(sizes: ImageSize[], opts?: CollageOpts): CollageLayout;
+/** "2 across", "stacked", "2 × 2" — how a layout is named in the picker. */
+export declare function collageLabel(count: number, cols: number): string;
+/**
+ * What the combined image IS, in one clause, for the agent that receives it.
+ *
+ * The panel numbers are drawn as PIXELS and nowhere else, so a prompt saying
+ * "the id in ② is the one missing in ③" is asking the reader to trust a badge it
+ * has to find first — and when the labels are off there is no badge at all, only
+ * an order the layout implies and the text never states. Both cases were the
+ * same silence: three screenshots arrived as one picture with no word about
+ * which end of it came first.
+ *
+ * So the arrangement is SAID: how many panels, how they run, and whether the
+ * numbers on them are real. It rides in the same `(marked: …)` clause as the
+ * marks (`web/src/annNote.ts`), which is the one place this repo lets an image
+ * carry words.
+ */
+export declare function collagePanelNote(count: number, cols: number, labelled: boolean): string;

package/node_modules/@waterplane/shared/dist/collage.js

@@ -0,0 +1,198 @@
+/**
+ * Several pictures as ONE picture — the geometry half.
+ *
+ * The reason this exists is marking, not tidiness. A bug that spans three
+ * screens (tap here, then this list, then this error) can only be circled
+ * across all three if all three are on one canvas: the annotator marks one
+ * image at a time, and an arrow cannot leave it. Sending three separately means
+ * describing the link between them in words, which is the thing a screenshot
+ * was supposed to replace.
+ *
+ * Pure, and here rather than in `web/` for the usual reason: the arrangement is
+ * the part that can be wrong (a column of phone screenshots is a 1:8 ribbon
+ * nobody can read on a phone), and pinning it needs `node --test`, not a
+ * browser. The pixels are pushed in `web/src/collage.ts`.
+ *
+ * Two rules carry the feature:
+ *
+ *  - **Rows normalize on HEIGHT, columns on nothing.** Each row scales its
+ *    images to a common height, so panels sit on a shared baseline and no
+ *    letterbox is needed in the direction that matters. Rows are then centered
+ *    inside the widest row, which is the only place slack can appear.
+ *  - **`pickCols` optimizes the resulting ASPECT, not the count.** Two portrait
+ *    screenshots side by side are ~0.9:1 and read perfectly; stacked they are
+ *    0.23:1, i.e. a ribbon that is 200 px wide by the time it fits a phone —
+ *    the marks on it would be unclickable. The same rule stacks landscape
+ *    captures, for the same reason in the other direction. That is the
+ *    "clever automatism": one number (`COLLAGE_TARGET_ASPECT`) and a search
+ *    over every column count, never a per-orientation special case.
+ */
+/**
+ * The shape the automatic pick aims at: slightly wider than tall.
+ *
+ * Not 1:1 and not 16:9. Square would put four phone screenshots in a 2×2 grid
+ * (right) but also three of them in a 2+1 grid with a hole in it (wrong — they
+ * are a sequence and read left to right). Anything wide enough to fix that
+ * would put four in a row, at which point each panel is a quarter of the phone
+ * wide. 1.25 is the value that gets both cases right, and the picker is one tap
+ * away for the case it doesn't.
+ */
+export const COLLAGE_TARGET_ASPECT = 1.25;
+/** Canvas caps. A phone re-encodes this before upload anyway (`uploadScale.ts`);
+ *  these exist so the CANVAS itself can be allocated on a mid-range device. */
+export const COLLAGE_MAX_SIDE = 4096;
+export const COLLAGE_MAX_PIXELS = 24e6;
+const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
+/** Sanitize a source size — a decode that reported 0 must not divide by it. */
+function norm(sizes) {
+    return sizes.map((s) => ({
+        w: Number.isFinite(s.w) && s.w > 0 ? s.w : 1,
+        h: Number.isFinite(s.h) && s.h > 0 ? s.h : 1,
+    }));
+}
+/** Row-major chunks of `cols`. The last row may be short — see `pickCols`. */
+function rowsOf(items, cols) {
+    const out = [];
+    for (let i = 0; i < items.length; i += cols)
+        out.push(items.slice(i, i + cols));
+    return out;
+}
+/**
+ * The gap between panels, derived from the images rather than fixed.
+ *
+ * A 12 px seam is a clear divider between two 400 px thumbnails and invisible
+ * between two 4K screenshots — and the second is the case this feature is for.
+ * Scaling it with the mean panel size keeps "these are two pictures" readable
+ * at every source resolution.
+ */
+export function defaultGap(sizes) {
+    const s = norm(sizes);
+    if (s.length < 2)
+        return 0;
+    const mean = s.reduce((a, x) => a + (x.w + x.h) / 2, 0) / s.length;
+    return clamp(Math.round(mean * 0.012), 4, 40);
+}
+/** Geometry at native scale, before the caps are applied. */
+function measure(sizes, cols, gap) {
+    const rows = rowsOf(sizes.map((s, i) => ({ ...s, i })), cols);
+    const rowBoxes = rows.map((row) => {
+        // Common height per row: the tallest member. Upscaling a small panel costs
+        // sharpness; letting rows disagree costs the shared baseline that makes a
+        // sequence readable, which is worth more.
+        const h = Math.max(...row.map((s) => s.h));
+        const cells = row.map((s) => ({ i: s.i, w: (s.w / s.h) * h, h }));
+        const w = cells.reduce((a, c) => a + c.w, 0) + gap * (row.length - 1);
+        return { h, w, cells };
+    });
+    const width = Math.max(...rowBoxes.map((r) => r.w));
+    const height = rowBoxes.reduce((a, r) => a + r.h, 0) + gap * (rowBoxes.length - 1);
+    const cells = [];
+    let y = 0;
+    for (const row of rowBoxes) {
+        // A short last row is centered, not left-aligned: a hole on one side reads
+        // as a missing panel, a hole on both reads as the end of the sequence.
+        let x = (width - row.w) / 2;
+        for (const c of row.cells) {
+            cells.push({ i: c.i, x, y, w: c.w, h: c.h });
+            x += c.w + gap;
+        }
+        y += row.h + gap;
+    }
+    return { width, height, cells, rows: rowBoxes.length };
+}
+/**
+ * How many images per row, judged only by the shape that comes out.
+ *
+ * Score is the log-distance from the target aspect, so 2× too wide and 2× too
+ * tall cost the same — a plain ratio would quietly prefer wide ribbons. The
+ * small raggedness penalty is the tie-break: with equal shapes on offer, the
+ * grid that leaves no hole wins.
+ */
+export function pickCols(sizes, gap = 0, targetAspect = COLLAGE_TARGET_ASPECT) {
+    const s = norm(sizes);
+    if (s.length < 2)
+        return 1;
+    let best = 1;
+    let bestScore = Infinity;
+    for (let cols = 1; cols <= s.length; cols++) {
+        const m = measure(s, cols, gap);
+        const ar = m.width / m.height;
+        const holes = cols * m.rows - s.length;
+        const score = Math.abs(Math.log(ar / targetAspect)) + 0.05 * (holes / s.length);
+        if (score < bestScore - 1e-9) {
+            bestScore = score;
+            best = cols;
+        }
+    }
+    return best;
+}
+/**
+ * The full arrangement, capped to something a phone can actually allocate.
+ *
+ * Rounding happens once, at the end, on already-scaled numbers: rounding the
+ * native geometry first and scaling the rounded values afterwards drifts the
+ * seams by a pixel per row, which is visible as a wobbling gap.
+ */
+export function layoutCollage(sizes, opts = {}) {
+    const s = norm(sizes);
+    if (!s.length)
+        return { cols: 0, rows: 0, gap: 0, width: 0, height: 0, scale: 1, cells: [] };
+    const gap = Math.max(0, Math.round(opts.gap ?? defaultGap(s)));
+    const cols = clamp(Math.round(opts.cols ?? pickCols(s, gap, opts.targetAspect)), 1, s.length);
+    const raw = measure(s, cols, gap);
+    const maxSide = opts.maxSide ?? COLLAGE_MAX_SIDE;
+    const maxPixels = opts.maxPixels ?? COLLAGE_MAX_PIXELS;
+    const scale = Math.min(1, maxSide / Math.max(raw.width, raw.height), opts.maxWidth && opts.maxWidth > 0 ? opts.maxWidth / raw.width : 1, Math.sqrt(maxPixels / (raw.width * raw.height)));
+    const width = Math.max(1, Math.round(raw.width * scale));
+    const height = Math.max(1, Math.round(raw.height * scale));
+    const cells = raw.cells.map((c) => {
+        const x = Math.round(c.x * scale);
+        const y = Math.round(c.y * scale);
+        return {
+            i: c.i,
+            x, y,
+            // Clamped so a rounded cell can never poke past the canvas it was
+            // measured inside — a drawImage past the edge is silently cropped, and
+            // the crop lands on the marked-up part as often as not.
+            w: Math.max(1, Math.min(Math.round(c.w * scale), width - x)),
+            h: Math.max(1, Math.min(Math.round(c.h * scale), height - y)),
+        };
+    });
+    return { cols, rows: raw.rows, gap: Math.round(gap * scale), width, height, scale, cells };
+}
+/** "2 across", "stacked", "2 × 2" — how a layout is named in the picker. */
+export function collageLabel(count, cols) {
+    if (count <= 1)
+        return "single";
+    if (cols === 1)
+        return "stacked";
+    if (cols >= count)
+        return `${count} across`;
+    return `${cols} × ${Math.ceil(count / cols)}`;
+}
+/**
+ * What the combined image IS, in one clause, for the agent that receives it.
+ *
+ * The panel numbers are drawn as PIXELS and nowhere else, so a prompt saying
+ * "the id in ② is the one missing in ③" is asking the reader to trust a badge it
+ * has to find first — and when the labels are off there is no badge at all, only
+ * an order the layout implies and the text never states. Both cases were the
+ * same silence: three screenshots arrived as one picture with no word about
+ * which end of it came first.
+ *
+ * So the arrangement is SAID: how many panels, how they run, and whether the
+ * numbers on them are real. It rides in the same `(marked: …)` clause as the
+ * marks (`web/src/annNote.ts`), which is the one place this repo lets an image
+ * carry words.
+ */
+export function collagePanelNote(count, cols, labelled) {
+    if (count <= 1)
+        return "";
+    const run = cols === 1
+        ? "stacked top to bottom"
+        : cols >= count
+            ? "in one row, left to right"
+            : `${cols} per row, left to right then down`;
+    return `collage of ${count} panels ${run}${labelled ? `, numbered 1-${count} in that order` : ", not numbered"}`;
+}
+//# sourceMappingURL=collage.js.map

package/node_modules/@waterplane/shared/dist/collage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collage.js","sourceRoot":"","sources":["../src/collage.ts"],"names":[],"mappings":"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"}

package/node_modules/@waterplane/shared/dist/contextweight.d.ts

@@ -0,0 +1,169 @@
+/**
+ * What a repo costs to have open, before anyone types anything.
+ *
+ * ── The thing being measured ────────────────────────────────────────────────
+ *
+ * `CLAUDE.md` is re-read on every turn of every session and every subagent, so
+ * its size is multiplied by everything the repo ever does. Measured on this
+ * desktop: one repo's had grown to 148,582 chars — ~37k tokens — and was **21%
+ * of every token that repo spent in a week**. Nobody did that on purpose. Each
+ * edit added a clause, every clause was worth writing, and none of them was the
+ * one that broke it.
+ *
+ * That is the shape of a problem a CHECK catches and a person does not: it has
+ * no moment of failure, only a slope.
+ *
+ * ── Always-on is not the same as total ─────────────────────────────────────
+ *
+ * A skill's BODY is loaded only when the skill is invoked, so a 20k skill costs
+ * nothing on a turn that never needed it. Its DESCRIPTION is in the listing on
+ * every turn. So the weight that matters is
+ *
+ *     CLAUDE.md + every skill's description
+ *
+ * and the skill bodies are reported beside it as what was successfully moved
+ * OFF the always-on path — a large body is evidence the split is working, not a
+ * problem. Counting them together would tell somebody who did the right thing
+ * that they had made it worse.
+ *
+ * ── Why it warns and never fails ───────────────────────────────────────────
+ *
+ * There is no correct size. A repo with genuine hard-won invariants may need a
+ * bigger file than a scratch project, and the person who wrote it is the only
+ * one who can say which half is reference. So this produces a number, a
+ * comparison and a sentence; the fix is a judgement call and is offered as a
+ * prompt, never applied.
+ */
+/** Chars per token, near enough for prose+markdown. Only ever used to SAY what
+ *  a size costs, never to decide anything — the thresholds are in chars. */
+export declare const CHARS_PER_TOKEN = 4;
+export interface ContextWeightLimits {
+    /** Always-on chars (CLAUDE.md + skill descriptions) before this warns. */
+    maxChars: number;
+    /** Always-on chars before it is called out loudly. */
+    hardChars: number;
+    /** Skills before their descriptions alone are worth a mention. */
+    maxSkills: number;
+}
+/**
+ * The defaults, and where they come from.
+ *
+ * `maxChars` 16,000 ≈ 4k tokens on every turn. Calibrated against the repo this
+ * was written in, after its reference had been moved into skills: 9,672 chars of
+ * CLAUDE.md plus 2,762 of skill descriptions = 12,434. A threshold that flags a
+ * repo which has already done the right thing is a threshold people learn to
+ * ignore, and the 2,762 is GOOD spend — it is what keeps 58k of reference off
+ * every turn. So the line sits above a well-organised repo and well below the
+ * 148k (37k tokens a turn) that prompted any of this.
+ *
+ * `hardChars` 40,000 ≈ 10k tokens a turn, where the cost stops being a rounding
+ * error on anything. `maxSkills` 30 is about descriptions, not bodies; they are
+ * already counted in `maxChars`, so the count trips only a listing that is itself
+ * a page — a router-plus-sub-skills split (24 here) is the shape the chars rule
+ * asks for.
+ *
+ * Override per host with `WATERPLANE_CONTEXT_WARN_CHARS` / `WATERPLANE_CONTEXT_HARD_CHARS` /
+ * `WATERPLANE_CONTEXT_MAX_SKILLS`.
+ */
+export declare const DEFAULT_CONTEXT_LIMITS: ContextWeightLimits;
+export interface SkillWeight {
+    name: string;
+    /** Frontmatter `description:` length — the part that is ALWAYS loaded. */
+    descChars: number;
+    /** Whole file. On-demand, reported as context, never counted against. */
+    bodyChars: number;
+}
+export interface ContextWeightInput {
+    /** `CLAUDE.md` plus any `.claude/CLAUDE.md`, in chars. */
+    claudeMdChars: number;
+    skills: SkillWeight[];
+}
+export type ContextWeightVerdict = "lean" | "heavy" | "steep";
+export interface ContextWeightReading {
+    verdict: ContextWeightVerdict;
+    /** What every turn carries: CLAUDE.md + all skill descriptions. */
+    alwaysOnChars: number;
+    alwaysOnTokens: number;
+    /** What was moved off the always-on path. Evidence, not debt. */
+    onDemandChars: number;
+    skillCount: number;
+    /** One sentence of fact. */
+    note: string;
+    /** What to do, when there is something worth doing. */
+    advice: string | null;
+}
+export declare function weighContext(input: ContextWeightInput, limits?: ContextWeightLimits, 
+/** Where each of those numbers came from. Absent = all shipped defaults,
+ *  which is what a caller with no store to consult is looking at. */
+sources?: Partial<ContextLimitSources>): ContextWeightReading;
+/**
+ * A file's YAML frontmatter as raw lines, or null when it has none. Tolerates what YAML loaders
+ * do — a UTF-8 BOM, blank lines before the opening `---`, CRLF and an empty block — because a
+ * strict match read such a skill's description as 0 chars and its whole text as body.
+ */
+export declare function frontmatterLines(text: string): string[] | null;
+/**
+ * The always-loaded length of one skill file: its `description:` frontmatter.
+ *
+ * Walked line by line rather than matched with one regex, because the obvious
+ * `/^description:([\s\S]*?)(?=\n\w+:|$)/m` is wrong in a way that reads as right:
+ * under `/m` the `$` is a LINE end, so a description wrapped across three lines
+ * measures as its first line — reporting a third of the cost of exactly the
+ * skills whose descriptions are worth looking at.
+ */
+export declare function skillDescChars(text: string): number;
+export type ContextLimitSource = "default" | "env" | "repo";
+export type ContextLimitSources = Record<keyof ContextWeightLimits, ContextLimitSource>;
+/** What the check used, where each number came from, and what is on file for
+ *  this repo — everything an editor needs to open on the right values without
+ *  hardcoding a default the host may change. */
+export interface ContextLimitsView {
+    /** The numbers the reading was actually taken against. */
+    effective: ContextWeightLimits;
+    source: ContextLimitSources;
+    /** The shipped defaults, for a truthful "back to default" label. */
+    defaults: ContextWeightLimits;
+    /** The env layer, as set on this host (absent fields = not exported). Shown
+     *  so a repo override that is being shadowed... cannot happen (repo wins),
+     *  but so "you set 20k on this host" is visible when a repo has no override. */
+    env: Partial<ContextWeightLimits>;
+    /** This repo's stored override, or null when it has none. The editor opens on
+     *  THIS, never on `effective`: they differ whenever env is doing the work. */
+    repo: Partial<ContextWeightLimits> | null;
+    /** Set only when resolution had to move a number the user gave — today the
+     *  single case is a `hardChars` left below a raised `maxChars`. Never silent. */
+    note?: string;
+}
+/** Bounds for a hand-typed threshold. Wide on purpose: this is a guard against a
+ *  typo and a zero, not an opinion about the right size — the module's whole
+ *  premise is that there isn't one. */
+export declare const CONTEXT_LIMIT_BOUNDS: Record<keyof ContextWeightLimits, {
+    min: number;
+    max: number;
+}>;
+/** A refusal sentence for one field, or null when the value is usable. Words,
+ *  not a clamp: a silently corrected threshold is a threshold that reports a
+ *  number the user never chose. */
+export declare function contextLimitError(field: keyof ContextWeightLimits, value: unknown): string | null;
+/**
+ * Read a client's patch into an override.
+ *
+ * A field that is absent or `null` is "leave it to the layer below" — that is
+ * how one knob is overridden without freezing the other two at whatever they
+ * happen to be today. An out-of-range field is REFUSED and named; the caller
+ * writes nothing and says so, rather than storing a repaired number.
+ */
+export declare function sanitizeContextLimits(patch: unknown): {
+    limits: Partial<ContextWeightLimits>;
+    errors: string[];
+};
+/**
+ * The three layers, resolved: repo override > host env > shipped default.
+ *
+ * `hardChars` below `maxChars` would make "steep" swallow "heavy" and leave the
+ * warn number quoted in a sentence that can never fire — the likely way to get
+ * there is raising a repo's warn line above the default hard line, i.e. the
+ * exact thing this feature is for. It is raised to match, and the move is
+ * REPORTED in `note` rather than applied quietly.
+ */
+export declare function resolveContextLimits(env?: Partial<ContextWeightLimits>, repo?: Partial<ContextWeightLimits> | null): ContextLimitsView;