waterplane 0.0.1 → 0.1.6

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

@@ -0,0 +1,122 @@
+import type { ScheduleRule } from "./schedule.js";
+/** What the probe found. `unknown` = this desktop cannot tell. */
+export type OptInState = "on" | "off" | "unknown";
+/** What the PERSON said about one offer in one repo. Absent = nothing. */
+export type OptInChoice = "declined" | "done";
+/** What a tap on the offer's verb does. */
+export type OptInAction = 
+/** Run the host's own setup fix with this id (`POST …/compliance/fix`). */
+{
+    kind: "fix";
+    fix: string;
+}
+/** Open the screen that already does this job. */
+ | {
+    kind: "open";
+    to: "series" | "capture";
+}
+/** Seed the Send sheet: these words, a new session in this repo. */
+ | {
+    kind: "agent";
+}
+/** Seed the Send sheet with a standing weekly rule and a model. */
+ | {
+    kind: "schedule";
+    days: number[];
+    hour: number;
+    minute: number;
+    graceMin: number;
+    model: string;
+};
+export interface OptInDef {
+    id: string;
+    title: string;
+    /** What it is and why someone would want it — one or two sentences. */
+    pitch: string;
+    /** What it spends, said plainly. Never a dollar figure nobody measured. */
+    cost: string;
+    /** The verb on the card, lower case. */
+    verb: string;
+    action: OptInAction;
+    /** The words handed to the agent (`agent`/`schedule` only), with `{repo}`
+     *  for the repo's name. Ends with the marker line where the host probes for
+     *  it (`optInMarker`). */
+    prompt?: string;
+}
+/** One offer as one repo answers it — the host's half. */
+export interface OptInRow {
+    id: string;
+    /** False = this offer does not fit this repo (no package.json for an npm
+     *  policy, say). Shown only behind a count, never as an offer. */
+    relevant: boolean;
+    state: OptInState;
+    /** What the probe saw, one sentence — names the file it read. */
+    detail: string;
+    choice?: OptInChoice;
+}
+/** `GET /api/repos/:id/optins`. */
+export interface OptInReport {
+    repoId: string;
+    repoName: string;
+    rows: OptInRow[];
+    checkedAt: number;
+}
+/** `POST /api/repos/:id/optins/choice` `{ id, choice }` (`choice: null` clears). */
+export interface OptInChoiceResult {
+    ok: boolean;
+    error?: string;
+    report?: OptInReport;
+}
+/**
+ * The line a seeded prompt ends with, so the host can tell a standing schedule
+ * this card made from any other one without matching on a label a person may
+ * have retyped. It is in the words on purpose: the person sees it before
+ * sending, and deleting it only means the card reads "off" — a reading that
+ * degrades to absent, never to a wrong "on".
+ */
+export declare function optInMarker(id: string): string;
+/**
+ * The catalog, in the order the cards are drawn. Add an offer here, give it a
+ * probe in `host/optins.ts`, and both ends pick it up.
+ */
+export declare const OPT_INS: readonly OptInDef[];
+export declare function optInDef(id: string): OptInDef | undefined;
+/** The words for an `agent`/`schedule` offer, for one repo — `null` for an
+ *  offer the agent does not run. */
+export declare function optInPrompt(id: string, repoName: string): string | null;
+/** The standing weekly rule a `schedule` offer seeds, in the phone's zone. */
+export declare function optInRule(id: string, tz: string): ScheduleRule | null;
+/**
+ * Which offers the sheet draws where — ONE function feeding every count and
+ * every cut, so the number on a control and the list it opens cannot disagree.
+ *
+ * - `offered`: relevant, not on, not declined, not marked done — the cards.
+ * - `active`: on by probe, or marked done by the person.
+ * - `declined`: the person said *not for me*.
+ * - `unfit`: does not fit this repo. Behind a count, never an offer.
+ *
+ * Rows the phone has no definition for (a newer desktop) are dropped: a card
+ * with no words is not an offer.
+ */
+export interface OptInCut {
+    offered: OptInRow[];
+    active: OptInRow[];
+    declined: OptInRow[];
+    unfit: OptInRow[];
+}
+export declare function optInCut(rows: readonly OptInRow[]): OptInCut;
+/** How an active row says it is on — the probe's word or the person's, never
+ *  one dressed as the other. */
+export declare function optInActiveWords(r: OptInRow): string;
+/**
+ * The *walk me through it* prompt: an agent that INTERVIEWS and then posts
+ * each picked offer as its OWN piece of work — never one long session doing
+ * all of them, which would re-send every earlier step on every turn of the
+ * next (`sessioncost.ts`).
+ *
+ * Only `agent`/`schedule` offers can be posted by an agent; `fix`/`open` ones
+ * are a tap on the phone, so they are named as such and left alone.
+ */
+export declare function optInWalkPrompt(offered: readonly OptInRow[], repoName: string): string | null;
+/** Strict reader for a row off the wire: unknown state/choice dropped, never rounded. */
+export declare function cleanOptInRow(x: unknown): OptInRow | null;

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

@@ -0,0 +1,252 @@
+/**
+ * **Opt-ins** — the advanced things a repo can turn on, as one catalog both ends
+ * read.
+ *
+ * The repo-setup checklist is hygiene: a fact against a line, pass/warn/fail,
+ * counted in the badge. Most of what waterplane can do for a repo is not that —
+ * a requirements list, a weekly security review, a pre-push hook are worth
+ * having, and a repo without them is not BROKEN. Putting them on the checklist
+ * would make a warn nobody can close (`compliance.ts`'s `visual-check` note
+ * argues the same), so they live here instead: a list of offers, each with
+ * three states the person controls — **on**, **off**, **not for me** — and
+ * counted in nothing.
+ *
+ * One registry, so the host's probe (`host/optins.ts`) and the phone's card
+ * (`OptInRegion.tsx`) are keyed by the same id and worded by the same strings.
+ *
+ * **Nothing here applies itself.** Every action is a tap: a `fix` runs the
+ * host's existing idempotent setup fix, `open` lands on the screen that already
+ * does the job, `agent` and `schedule` SEED the Send sheet — the words, the
+ * repo, and for a schedule the clock and the model — and nothing is sent until
+ * the person sends it there, where all of it can still be changed.
+ *
+ * **A probe answers `on`, `off` or `unknown`, never a guess.** `unknown` is an
+ * offer the desktop cannot check (a cloud registry's policy); the person can
+ * mark it done, and that is stored as THEIR word (`choice: "done"`) and shown as
+ * such, never as a probe that passed.
+ */
+import { BRAND } from "./brand.js";
+/**
+ * The line a seeded prompt ends with, so the host can tell a standing schedule
+ * this card made from any other one without matching on a label a person may
+ * have retyped. It is in the words on purpose: the person sees it before
+ * sending, and deleting it only means the card reads "off" — a reading that
+ * degrades to absent, never to a wrong "on".
+ */
+export function optInMarker(id) {
+    return `(${BRAND.slug} opt-in: ${id})`;
+}
+const SECURITY_PROMPT = `Weekly security review of {repo}. Read-only: change no file, commit nothing, push nothing.
+
+1. Read what changed since the last review (\`git log --since="8 days ago" --stat\`, then the diffs that touch auth, input handling, file paths, shell/process spawning, network listeners, secrets or dependencies).
+2. Check the dependency manifests and lockfiles for new or bumped packages, install scripts and known-vulnerable versions (\`npm audit --omit=dev\` or the ecosystem's equivalent, if it runs offline-safe).
+3. Look for secrets committed by accident (keys, tokens, .env files) in the changed files.
+
+Write the findings to \`.claude/outbox/security-review-<YYYY-MM-DD>.md\`: each finding with severity (high/medium/low), the file and line, why it matters, and a proposed fix as words. If nothing was found, write that and what you checked. Do not fix anything — the person decides.
+
+${"{marker}"}`;
+/**
+ * The catalog, in the order the cards are drawn. Add an offer here, give it a
+ * probe in `host/optins.ts`, and both ends pick it up.
+ */
+export const OPT_INS = [
+    {
+        id: "requirements",
+        title: "Requirements list",
+        pitch: "A list of what this repo is expected to do, rebuilt from your own prompts and commits, so an agent checks it before changing behaviour you rely on.",
+        cost: "Setting it up writes two files and spends nothing. Each later build is one paid run, and the setup checklist's row says when one is due.",
+        verb: "set it up",
+        action: { kind: "fix", fix: "requirements" },
+    },
+    {
+        id: "repo-health",
+        title: "Repo health series",
+        pitch: "Size, complexity, churn and test readings for this repo, measured weekly and drawn as a trend, so a slow slide shows up before it hurts.",
+        cost: "Spends no tokens: a local tool runs once a week while the desktop is up. The first measurement is a tap on the series screen.",
+        verb: "open the series",
+        action: { kind: "open", to: "series" },
+    },
+    {
+        id: "repo-health-own",
+        title: "Your own health readings",
+        pitch: "Numbers only this repo knows about itself (test count, bundle size, open TODOs), measured beside the standard ones in the same weekly series.",
+        cost: "One agent session to propose them. The readings themselves spend no tokens.",
+        verb: "propose readings",
+        action: { kind: "agent" },
+        prompt: `Propose 2-4 repo-specific health readings for {repo}: numbers this repo knows about itself that a generic metric cannot (for example test count, bundle size, number of TODO/FIXME, count of skipped tests).
+
+They are declared in \`{shared}/health.json\` as
+{ "readings": [ { "key": "testCount", "name": "Tests", "means": "one sentence", "better": "higher" | "lower", "unit": "tests", "run": ["node", "tools/health/testcount.mjs"] } ] }
+\`run\` is an argv array (no shell), run from the repo root, and must print ONE JSON number or {"value": n} to stdout; anything else makes the reading absent.
+
+Show me the readings you propose and the small scripts behind them before writing anything. Only declarations that are committed run, so after I agree, write the files and tell me to commit them.
+
+{marker}`,
+    },
+    {
+        id: "security-review",
+        title: "Weekly security review",
+        pitch: "Every Monday a session reads the week's changes and dependency bumps and writes its findings to the outbox. It changes nothing; you decide what to fix.",
+        cost: "One Fable session a week, the most capable and most expensive model, picked on purpose. You can change the model, day and time before you save it, and each run's cost shows on its row.",
+        verb: "schedule it",
+        action: { kind: "schedule", days: [1], hour: 9, minute: 0, graceMin: 12 * 60, model: "fable" },
+        prompt: SECURITY_PROMPT,
+    },
+    {
+        id: "local-ci",
+        title: "Checks before every push",
+        pitch: "A git pre-push hook that runs this repo's tests and lint on your desktop, so a broken push is caught without paying for hosted CI minutes.",
+        cost: "One agent session to set it up. After that the hook runs locally and spends no tokens.",
+        verb: "set it up",
+        action: { kind: "agent" },
+        prompt: `Set up a local pre-push check for {repo}, so tests and lint run on this desktop before every push instead of in hosted CI.
+
+1. Find the commands this repo already uses to lint, type-check and test (package.json scripts, Makefile, pyproject, CI config).
+2. Propose one pre-push hook: what it runs, in what order, roughly how long it takes. Keep it fast enough that people will not skip it; slow suites can be a separate command.
+3. Show me the hook before installing it. Prefer a committed hooks directory (\`git config core.hooksPath\`) so it survives a fresh clone, and say how to bypass it in an emergency.
+
+Do not change the tests or the lint rules themselves.
+
+{marker}`,
+    },
+    {
+        id: "npm-supply-chain",
+        title: "Safer npm installs",
+        pitch: "An .npmrc that stops dependencies running code at install time and waits a few days before taking a freshly published version, when most hijacked releases are caught.",
+        cost: "One short agent session. It spends nothing afterwards.",
+        verb: "set it up",
+        action: { kind: "agent" },
+        prompt: `Harden npm installs in {repo} with a committed \`.npmrc\`:
+
+- \`ignore-scripts=true\`: no dependency runs code at install time. First list which dependencies have install scripts (preinstall/install/postinstall) and say, per one, whether it works without it (prebuilds) or needs a replacement step in our own build.
+- \`min-release-age=7\`: a version must be a week old before \`npm install\` picks it. Check the installed npm version supports it and say so if it does not.
+
+Show me the file and the list before writing. \`npm ci\` from the lockfile is unaffected; say that in a comment in the file.
+
+{marker}`,
+    },
+    {
+        id: "gcp-cleanup",
+        title: "Registry cleanup policy (GCP)",
+        pitch: "Cloud Run scales to zero; its Artifact Registry does not. One image per deploy piles up and bills as storage until a cleanup policy deletes the old ones.",
+        cost: "One agent session. The policy usually lowers the storage bill. The desktop cannot check it from here, so mark it done once it is set.",
+        verb: "set it up",
+        action: { kind: "agent" },
+        prompt: `{repo} deploys to Google Cloud. Check its Artifact Registry repositories and set a cleanup policy so images stop piling up:
+
+1. List the registry repos this project deploys to and their size (\`gcloud artifacts repositories list\`, and describe each one).
+2. Propose a policy (keep the 5 most recent versions, delete older than 7 days) and show it with \`--dry-run\` first.
+3. Never delete the image the live Cloud Run revision serves; a keep-recent rule protects it. Name that digest.
+
+Apply with \`--no-dry-run\` only after I agree. The size metric lags about 24h after a delete; say so.
+
+{marker}`,
+    },
+    {
+        id: "screenshots",
+        title: "Screenshots of your app",
+        pitch: "Let an agent (and you, from the phone) capture this app's screens on the desktop and check them, instead of describing what it probably looks like.",
+        cost: "Setting up a capture target spends nothing. Each screenshot an agent looks at costs tokens on every later turn, and the checklist then offers the skill that keeps that cheap.",
+        verb: "open captures",
+        action: { kind: "open", to: "capture" },
+    },
+];
+const BY_ID = new Map(OPT_INS.map((d) => [d.id, d]));
+export function optInDef(id) {
+    return BY_ID.get(id);
+}
+/** The words for an `agent`/`schedule` offer, for one repo — `null` for an
+ *  offer the agent does not run. */
+export function optInPrompt(id, repoName) {
+    const d = BY_ID.get(id);
+    if (!d?.prompt)
+        return null;
+    return d.prompt.replaceAll("{repo}", repoName).replaceAll("{marker}", optInMarker(id))
+        .replaceAll("{shared}", BRAND.sharedDirName).replaceAll("{skill}", BRAND.skillName);
+}
+/** The standing weekly rule a `schedule` offer seeds, in the phone's zone. */
+export function optInRule(id, tz) {
+    const a = BY_ID.get(id)?.action;
+    if (a?.kind !== "schedule")
+        return null;
+    return { kind: "weekly", days: [...a.days], hour: a.hour, minute: a.minute, tz };
+}
+export function optInCut(rows) {
+    const cut = { offered: [], active: [], declined: [], unfit: [] };
+    for (const r of rows) {
+        if (!BY_ID.has(r.id))
+            continue;
+        if (r.choice === "declined")
+            cut.declined.push(r);
+        else if (r.state === "on" || r.choice === "done")
+            cut.active.push(r);
+        else if (!r.relevant)
+            cut.unfit.push(r);
+        else
+            cut.offered.push(r);
+    }
+    return cut;
+}
+/** How an active row says it is on — the probe's word or the person's, never
+ *  one dressed as the other. */
+export function optInActiveWords(r) {
+    return r.state === "on" ? "on" : "marked done by you";
+}
+/**
+ * The *walk me through it* prompt: an agent that INTERVIEWS and then posts
+ * each picked offer as its OWN piece of work — never one long session doing
+ * all of them, which would re-send every earlier step on every turn of the
+ * next (`sessioncost.ts`).
+ *
+ * Only `agent`/`schedule` offers can be posted by an agent; `fix`/`open` ones
+ * are a tap on the phone, so they are named as such and left alone.
+ */
+export function optInWalkPrompt(offered, repoName) {
+    const defs = offered.map((r) => BY_ID.get(r.id)).filter((d) => !!d);
+    if (defs.length === 0)
+        return null;
+    const postable = defs.filter((d) => d.action.kind === "agent" || d.action.kind === "schedule");
+    const taps = defs.filter((d) => d.action.kind === "fix" || d.action.kind === "open");
+    const lines = [
+        `Walk me through the optional features ${BRAND.displayName} offers for ${repoName}. Do NOT set any of them up in this session.`,
+        "",
+        "1. For each one below, look at the repo briefly and tell me in one or two lines whether it fits here and what it would take. Then ask me which ones I want, in ONE question.",
+        `2. For each one I pick, post its prompt (quoted below, unchanged) as its own new-session work item in this repo, using the ${BRAND.skillName} skill's way of posting work for later. A schedule one is posted as a weekly schedule with the model named. Do not run them here.`,
+        "3. Finish with a list of what you posted, and nothing else.",
+        "",
+    ];
+    for (const d of postable) {
+        const when = d.action.kind === "schedule"
+            ? ` — weekly, ${dayName(d.action.days)} ${pad2(d.action.hour)}:${pad2(d.action.minute)}, model ${d.action.model}`
+            : "";
+        lines.push(`## ${d.title}${when}`, d.pitch, d.cost, "", "Prompt:", "```", optInPrompt(d.id, repoName) ?? "", "```", "");
+    }
+    if (taps.length) {
+        lines.push("These are a tap on the phone's Opt-ins screen, not something to post. Just say whether they fit:");
+        for (const d of taps)
+            lines.push(`- ${d.title}: ${d.pitch}`);
+    }
+    return lines.join("\n").trimEnd();
+}
+const DAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+function dayName(days) {
+    return days.length === 0 ? "every day" : days.map((d) => DAYS[d] ?? "?").join(", ");
+}
+function pad2(n) {
+    return String(n).padStart(2, "0");
+}
+/** Strict reader for a row off the wire: unknown state/choice dropped, never rounded. */
+export function cleanOptInRow(x) {
+    if (!x || typeof x !== "object")
+        return null;
+    const o = x;
+    if (typeof o.id !== "string" || typeof o.relevant !== "boolean")
+        return null;
+    if (o.state !== "on" && o.state !== "off" && o.state !== "unknown")
+        return null;
+    const row = { id: o.id, relevant: o.relevant, state: o.state, detail: typeof o.detail === "string" ? o.detail : "" };
+    if (o.choice === "declined" || o.choice === "done")
+        row.choice = o.choice;
+    return row;
+}
+//# sourceMappingURL=optins.js.map

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

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

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

@@ -0,0 +1,263 @@
+/**
+ * The pad, as a value two devices can both write to without deleting each
+ * other's words.
+ *
+ * The pad is a synced setting, and a synced setting is an OPAQUE STRING with
+ * one `ts` — the host never parses it (`shared/settings.ts` argues why at
+ * length). So the merge the host can perform is last-write-wins on the whole
+ * value: a device that pushes its pad while holding an older copy replaces
+ * every note the other one had, with no diff, no warning, and nothing on the
+ * wire that distinguishes it from a deliberate delete. For a preference that is
+ * the right rule; for the store whose entire job is to be the last copy of
+ * words that never ran, it is a silent delete.
+ *
+ * Everything that used to compensate for that — a diff that guessed which
+ * drops were losses, a device-local rescue store, an amber "N notes were kept
+ * for you" block — is gone, because the merge is fixed instead. The CLIENT
+ * merges per note on adopt (`web/settings.ts`'s `onAdopt`), the host still
+ * stores a string and still compares a `ts`, and nothing on the wire changed.
+ *
+ * ── The shape, and why it is still one array ──────────────────────────────
+ *
+ * The synced value stays ONE JSON array under `waterplane.pad`, with two element
+ * shapes discriminated by their fields: a note has a string `text`, a
+ * tombstone has a finite `gone` and no text. It is not `{v:2,notes,tombs}`,
+ * which would have been tidier, because an older bundle's `loadPad` and its
+ * `onAdopt` guard both filter to elements with a string `text` — against an
+ * array they drop the tombstones silently and keep a working pad, where
+ * against an object they would show the user an EMPTY pad. The host's
+ * `padNotesFor` already skips text-less elements for the same reason.
+ *
+ * ── The failure mode this chooses ─────────────────────────────────────────
+ *
+ * A legacy array parses as a `PadDoc` with `tombs: []`. So a delete made on a
+ * device still running an old bundle — or one that fell more than
+ * `PAD_TOMB_TTL_MS` behind the newest words either copy carries — is forgotten,
+ * and the note comes back once, everywhere, wearing its original date. That
+ * costs one tap. The failure it replaces cost words.
+ *
+ * Pinned by `packages/shared/test/pad.test.mjs`.
+ */
+/** One note on the pad. */
+export interface PadNote {
+    id: string;
+    text: string;
+    /**
+     * When this note was last WRITTEN — not when it was first thought of.
+     *
+     * `PadSheet.commit()` stamps `Date.now()` on every save, an edit of an
+     * existing note included, so this is a per-note edit stamp and that is what
+     * `mergePad` compares. A field that only recorded creation could not decide
+     * which of two copies of one id is the newer one, which is the whole merge.
+     */
+    ts: number;
+    /** The rest of the chain — the steps after `text`, each delivered only once
+     *  the one before it has finished its turn. Beside the text, never inside it. */
+    steps?: string[];
+    /** The repo this note was written FOR, when it has one: a note that names
+     *  `.claude/inbox/…` paths only means anything inside one worktree, and a note
+     *  that names a repo can be filed straight onto that repo's backlog. Absent on
+     *  a hand-written note, which is the ordinary case. */
+    cwd?: string;
+}
+/**
+ * A delete, as something that can travel.
+ *
+ * Without one, "this note is not in my copy" is indistinguishable from "I have
+ * not seen this note yet", and a union merge would resurrect every note anybody
+ * ever deleted, for ever.
+ */
+export interface PadTombstone {
+    id: string;
+    gone: number;
+}
+/** The pad as this module reasons about it. */
+export interface PadDoc {
+    notes: PadNote[];
+    tombs: PadTombstone[];
+}
+/**
+ * Hard bounds on the pad — a COUNT that rarely binds and a BYTE budget that does.
+ *
+ * The pad is not a scratch list. It holds words that have no target yet, which
+ * is the one kind this app cannot reconstruct from anywhere else. Both bind on
+ * a LOCAL ADD only, and an add past them is REFUSED rather than silently
+ * shedding the oldest note — a refusal leaves the words in the editor, where
+ * their author can see them; shedding deleted a note precisely because it was
+ * old, and a note is old exactly when nobody has dealt with it yet.
+ */
+export declare const PAD_CAP = 400;
+export declare const PAD_BYTES: number;
+/**
+ * How long a tombstone suppresses the note it names: 30 days.
+ *
+ * The argument is "how long may a device be offline before its stale copy is
+ * allowed to resurrect a delete", not the retired rescue store's 7 days, which
+ * measured something else entirely. A month is the longest a phone left in a
+ * drawer plausibly stays paired; past that the delete is forgotten and the
+ * stale copy comes back once, wearing its old date.
+ *
+ * Measured against the PAD's own newest stamp, never against a device clock —
+ * `mergePad` argues why at length. So "30 days" means 30 days of the pad being
+ * written to without this delete travelling, which is the thing the number was
+ * ever a guess about.
+ */
+export declare const PAD_TOMB_TTL_MS: number;
+/** Tombstones are capped like notes, newest `gone` kept. Same number, because
+ *  the worst case is one tombstone per note and there is no reason for the two
+ *  halves of one value to have different ceilings. */
+export declare const PAD_TOMB_CAP = 400;
+/**
+ * Read the stored value, tolerating everything.
+ *
+ * Nothing here throws and nothing here is authoritative: a value written by a
+ * newer bundle, an older one, or half a bundle must still produce a pad
+ * somebody can use. Not an array (or unparseable) is an EMPTY doc, never an
+ * error — the alternative is a sheet that cannot render.
+ */
+export declare function parsePad(raw: string | null | undefined): PadDoc;
+/**
+ * The value this device writes — CANONICAL, and that is load-bearing.
+ *
+ * Notes newest first (`ts` desc, then `id` asc), tombstones after them
+ * (`gone` desc, then `id` asc), keys in a fixed order. The convergence in
+ * `web/settings.ts` terminates only because two devices holding the same set of
+ * notes produce byte-identical strings: the loser of a concurrent push
+ * re-merges the winner's value, gets exactly that string back, and
+ * `applyRemoteSetting`'s equality branch stops the exchange. A serializer that
+ * ordered by insertion would hand the two devices two different strings for one
+ * pad, and they would push at each other until one of them was closed.
+ */
+export declare function serializePad(doc: PadDoc): string;
+/**
+ * Two copies of the pad, one pad.
+ *
+ * Commutative and idempotent by construction, which is what lets both devices
+ * run it on whatever they happen to hold and land on the same value:
+ *
+ *  1. **Tombstones union** by id, greater `gone` wins; anything older than
+ *     `PAD_TOMB_TTL_MS` **before the newest stamp in the union** is forgotten.
+ *  2. **Per note id**, the copy with the greater `ts` is the candidate. On an
+ *     exact tie the one whose canonical JSON sorts lexically LATER wins —
+ *     "prefer mine" would make the function non-commutative, i.e. the two
+ *     devices would converge on two different values and push for ever.
+ *  3. A tombstone with `gone >= candidate.ts` drops the note. A candidate whose
+ *     `ts` is GREATER than the tombstone's `gone` keeps the note **and drops
+ *     the tombstone**: those are words somebody typed after the delete, and the
+ *     delete was made on a device that had not seen them.
+ *  4. **Then** the newest `PAD_TOMB_CAP` tombstones are kept.
+ *  5. **No note is ever dropped for size here.** The caps bind on a local add,
+ *     where a person is present to be told. A merge that shed notes would
+ *     delete words on the device that was merely receiving them.
+ *
+ * ── Why the TTL is cut on the DATA and not on a clock ─────────────────────
+ *
+ * "Same union ⇒ same bytes" is the whole contract, and a `Date.now()` anywhere
+ * inside it breaks that between two devices whose clocks disagree — which is
+ * every pair of devices. Trace the version that read the clock: A is two hours
+ * behind B, and a tombstone `T` has `gone` between the two cutoffs. A merges
+ * the host's value, keeps `T`, sees `changed`, pushes. B adopts it, drops `T`,
+ * sees `changed`, pushes. A adopts THAT, re-adds `T`, pushes — one round per
+ * `PUSH_DEBOUNCE_MS` for the whole skew window, each one re-stamping the
+ * setting and firing `announce`, and neither device is wrong.
+ *
+ * So the cutoff is `max(every ts and every gone across both copies) −
+ * PAD_TOMB_TTL_MS`. It is a fact about the two documents, so both devices
+ * compute it identically and the function is a pure fold over the union again.
+ * The cost is that the newest tombstone in a pad nobody touches is never aged
+ * out — which is correct: "30 days" was always meant as *30 days of the pad
+ * moving on without this delete*, and a pad that has not moved has no newer
+ * words for a stale copy to overwrite.
+ *
+ * `now` is therefore UNREAD, and kept in the signature deliberately: the call
+ * sites pass it, and `pad.test.mjs` hands the two sides wildly different values
+ * and asserts the bytes are identical, which is a pin a removed parameter
+ * could not carry.
+ *
+ * ── Why the cap is applied AFTER rule 3 ───────────────────────────────────
+ *
+ * Cutting to `PAD_TOMB_CAP` first meant the resurrection rule then deleted
+ * tombstones out of an already-cut list, so the output could hold fewer than
+ * the cap while the union still held tombstones that belonged in it — and the
+ * next exchange with the same peer put them back. The merged value was not a
+ * fixed point of merging with its own input, which is the same
+ * push-at-each-other loop by another route. Resurrect first, cut last: the cut
+ * is then a function of what actually survived.
+ */
+export declare function mergePad(mine: PadDoc, theirs: PadDoc, _now?: number): PadDoc;
+/**
+ * Delete notes — and say so in a way that travels.
+ *
+ * A tombstone is written for every id, INCLUDING ids this device has never
+ * seen: a delete made against a note that only exists on the other device still
+ * has to reach it, and "I do not have it" is not a delete.
+ */
+export declare function removeNotes(doc: PadDoc, ids: readonly string[], now: number): PadDoc;
+/** Write a note, by id — and forget any delete for it, since this is somebody
+ *  typing after that delete, which is rule 3 stated locally. */
+export declare function upsertNote(doc: PadDoc, note: PadNote): PadDoc;
+/**
+ * A remote value is about to replace this device's copy: merge instead.
+ *
+ * `changed` says the merged value differs from what arrived — i.e. this device
+ * holds something the host does not, and has to push it back. An incoming `""`
+ * is an EMPTY doc rather than "no opinion", so a removal on the wire cannot
+ * take this device's notes with it: they survive the merge and go back up.
+ */
+export declare function adoptPad(incomingRaw: string, currentRaw: string | null, now: number): {
+    value: string;
+    changed: boolean;
+};
+/** What the pad IS, at the top of the sheet. */
+export declare const PAD_HINT: string;
+/** The refusal: the add did not happen, and the words are still where you can
+ *  see them. Never a shed note — that deleted somebody's words to make room for
+ *  somebody's words. */
+export declare function padFullText(n: number, kb: number): string;
+/** The other refusal: this browser refused the write outright (private mode, an
+ *  origin at quota). Same promise — the words did not move. */
+export declare const PAD_WRITE_REFUSED = "this phone's storage refused the note \u2014 your text is still in the editor; free some space, or send or clear a note first";
+/** The retired device-local rescue store, handed back to the pad it was
+ *  guarding. Said once, on the boot that moves them. */
+export declare function padMigratedToast(n: number): string;
+/** A half-written prompt about to be replaced by words nobody typed, parked
+ *  where there is a listing to find it again. */
+export declare const DRAFT_KEPT_TOAST = "kept your unfinished prompt \u2014 it is a note on the pad";
+/** …and when the pad could not take it. The draft is NOT overwritten: a rescue
+ *  that failed must not also be a delete. */
+export declare const DRAFT_REFUSED_TOAST = "the pad could not take your unfinished prompt, so it was left in the box \u2014 nothing was replaced";
+/** *file it* — the verb for a note that already knows which repo it is for. */
+export declare const FILE_WORDS: {
+    label: string;
+    title: (repo: string) => string;
+};
+/** What filing did. Offline is its own sentence: the row is durable either way,
+ *  and a promise about "when the link is back" is the honest half. */
+export declare function padFiledToast(repo: string, offline: boolean): string;
+/**
+ * A draft about to be replaced by words nobody typed — what, if anything, to
+ * keep.
+ *
+ * The merge above guards the pad against a synced overwrite. This guards the
+ * *sheet drafts* against the local equivalent, and the local one is worse: the
+ * sheet-draft store has no listing of its own, so the only route back to a
+ * draft is re-opening the exact sheet that wrote it. When anything breaks that
+ * single route — a routing bug, a reload, an OTA bundle swap, a killed tab —
+ * the words still exist and nothing on the phone can reach them, and the next
+ * open of that sheet seeds the slot and deletes them. A prompt typed on a
+ * train, with a schedule set and a screenshot marked up, went that way.
+ *
+ * Two things are NOT rescued, and both are the ordinary case: an empty slot
+ * (nothing to keep), and a slot that already holds exactly the incoming seed
+ * (re-opening the same message is not an overwrite). Whitespace-only counts as
+ * empty — a stray newline is not a draft, and a rescue row for one teaches the
+ * user to ignore the section.
+ *
+ * Returns the chain SPLIT: `text` is the first step and `steps` the rest, which
+ * is the shape a pad note wants (`PadNote.steps`) rather than a string with
+ * control characters in it.
+ */
+export declare function draftToRescue(current: string, seed: string): {
+    text: string;
+    steps?: string[];
+} | null;