@catalyst-cloud/cli 0.15.3 → 0.15.5

package/dist/onboard-ui.js

@@ -1,12 +1,19 @@
 import { COMPUTER_CHECKS, standalonePlan, standalonePlanNotes, pendingContinuation, } from "./onboard-standalone-copy.js";
 import { trackedPrompt } from "./setup-prompt-frame.js";
 import { createOnboardInterrupts } from "./onboard-interrupts.js";
-import { setupStepView, CONNECTION_REPAIR_REASONS, setupFinalScreen, setupBrowserInstruction, setupCommandWords as say, setupPartHeading, setupPartProgress, setupTrackerRows, SETUP_PART_NUMBERS, SETUP_PART_OF, SETUP_PARTS, } from "./setup-onboard-copy.js";
+import { setupStepView, CONNECTION_REPAIR_REASONS, setupFinalScreen, setupBrowserInstruction, setupCommandWords as say, setupWaitsOnAdmin, TIMED_OUT_REASONS, setupPartHeading, setupPartProgress, setupTrackerRows, SETUP_PART_NUMBERS, SETUP_PART_OF, SETUP_PARTS, } from "./setup-onboard-copy.js";
 import { createOnboardProgress, } from "./onboard-progress.js";
 import { CREATE_TEAM_CHOICE, suggestTeamKey, teamKeyProblem, teamNameProblem, } from "./onboard-team-create.js";
 import { FIRST_TICKET_SAMPLE, FIRST_TICKET_SKIP, } from "./onboard-first-ticket.js";
-import { ONBOARD_STEPS, ONBOARD_TITLES, stepSatisfied, onboardIdentityLines, onboardNextActions, onboardReadyForWork, onboardStepAction, } from "./onboard.js";
+import { ONBOARD_STEPS, ONBOARD_TITLES, stepSatisfied, onboardHeaderIdentity, onboardIdentityLines, onboardNextActions, onboardReadyForWork, onboardStepAction, } from "./onboard.js";
 import { onboardStepDetail, onboardReasonText } from "./onboard-next.js";
+import { CONNECT_PAGE_PATH } from "./onboard-checklist.js";
+/** What the runner question's answers mean, said before it is asked (CTC-4739). */
+const RUNNER_EXPLAINED = [
+    "Yes makes this computer pick up tickets and run agents in Docker with your workspace's AI accounts. It uses this computer's CPU and memory while it is on, and turning it off or letting it sleep pauses that work.",
+    "No is right for a personal workstation: your workspace's runner hosts do the work.",
+    "Pass --no-runner or --runner to skip this question next time.",
+];
 export function shouldUseOnboardUi(args, stdoutTty) {
     return (stdoutTty &&
         !args.json &&
@@ -43,6 +50,11 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
     let planned = {};
     let rechecking = false;
     let shownPlan;
+    // CTC-4680: steps whose wait was on the Connect accounts page. That page does not expire, so a
+    // wait that ran out is setup giving up, and the way back is the same page.
+    const connectWaits = new Map();
+    const onConnectPage = (step) => connectWaits.has(step.id) && TIMED_OUT_REASONS.has(step.reason ?? "");
+    const outcome = (step, view) => onConnectPage(step) ? "setup stopped waiting" : view.outcome;
     let browserOpened = true;
     let questionOpen = false;
     let signinShown = false;
@@ -98,11 +110,15 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             renderer.heading(setupPartHeading(next, renderer.traits.unicode));
             return;
         }
-        const progress = setupPartProgress(journalSeen, planned.scope);
-        const left = progress[previous].total - progress[previous].done;
-        renderer.heading(left
-            ? `Part ${previous} has ${left === 1 ? "1 step" : `${left} steps`} left. Setup carries on with part ${next}.`
-            : `Part ${previous} done. ${SETUP_PARTS[previous].done}`);
+        const progress = setupPartProgress(journalSeen, planned.scope, "run");
+        const got = progress[previous];
+        const left = got.total - got.done;
+        // Mid-run nothing yet says whether an owner or admin has done their part, so this is neutral.
+        renderer.heading(!left
+            ? `Part ${previous} done. ${SETUP_PARTS[previous].done}`
+            : left === got.admin + got.aside
+                ? `The rest of part ${previous} is for an owner or admin of your Catalyst workspace.`
+                : `Part ${previous} has ${left === 1 ? "1 step" : `${left} steps`} left. Setup carries on with part ${next}.`);
         renderer.tracker(setupTrackerRows(progress, { next }));
         planPart(renderer, next, journalSeen);
         renderer.blank();
@@ -221,10 +237,54 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
         return result.answer;
     };
     let summaryShown = false;
-    const summary = (journal) => {
+    /**
+     * The end screen's actions, split by who acts: the person's own, and an owner's or admin's
+     * (CTC-4680). A step paused with Ctrl-C is not an action: the last line says how to carry on.
+     */
+    const sortActions = (journal) => {
         const screen = setupFinalScreen(journal, deps.baseUrl?.(), abort.signal.aborted);
+        const step = (id) => journal.steps.find((s) => s.id === id) ?? { id, state: "pending" };
+        const text = (action) => {
+            const row = step(action.id);
+            if (!onConnectPage(row))
+                return say(action.text);
+            const kinds = row.evidence?.aiAccountKinds;
+            // #277's rule: subscription wording only for a workspace the cloud enables for it.
+            const what = action.id === "accounts"
+                ? typeof kinds === "string" && kinds.split(",").includes("subscription")
+                    ? "add an API key or connect a subscription"
+                    : "add an API key"
+                : action.id === "github.install"
+                    ? "install Catalyst on GitHub"
+                    : `finish "${title(action.id)}" there`;
+            return `Open ${connectWaits.get(action.id)} and ${what}.`;
+        };
+        const live = screen.actions.filter((action) => step(action.id).reason !== "interrupted");
+        const theirs = live.filter((action) => setupWaitsOnAdmin(step(action.id), journal));
+        const mine = live.filter((action) => !theirs.includes(action));
+        // Steps only an owner or admin can do, less any already listed as their task above.
+        const skipped = journal.steps.filter((s) => s.reason === "member_scope" &&
+            setupWaitsOnAdmin(s, journal) &&
+            SETUP_PART_NUMBERS[s.id] !== undefined &&
+            s.id !== "projects" &&
+            !theirs.some((action) => action.id === s.id));
+        const waiting = theirs.length > 0 || skipped.length > 0;
+        const own = mine.length;
+        const next = screen.paused ||
+            !/^Next: run catalyst onboard after you finish/.test(screen.next)
+            ? say(screen.next)
+            : own
+                ? `Next: run catalyst setup after you finish ${own === 1 ? "1" : own === 2 ? "1 and 2" : `1 to ${own}`}.`
+                : waiting
+                    ? "Next: run catalyst setup once they have."
+                    : "Next: run catalyst setup to check again.";
+        return { screen, mine, theirs, skipped, waiting, next, text, live };
+    };
+    const summary = (journal) => {
+        const sorted = sortActions(journal);
+        const { screen, mine, theirs, skipped } = sorted;
         if (!renderer)
-            return screen;
+            return sorted;
         renderer.suspendLive();
         active = false;
         renderer.heading(screen.heading);
@@ -233,12 +293,34 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
         renderer.tracker(setupTrackerRows(setupPartProgress(journal, planned.scope), "end"));
         if (screen.readinessCause)
             renderer.line(say(screen.readinessCause));
-        if (screen.actions.length) {
-            renderer.line(`${screen.actions.length} ${screen.actions.length === 1 ? "thing needs" : "things need"} you:`);
-            screen.actions.forEach((action, i) => renderer.item(`${i + 1}. `, say(action.text)));
+        if (mine.length) {
+            renderer.line(`${mine.length} ${mine.length === 1 ? "thing needs" : "things need"} you:`);
+            mine.forEach((action, i) => renderer.item(`${i + 1}. `, sorted.text(action)));
             if (screen.more)
                 renderer.line(`and ${screen.more} more after these`);
-            const continuation = pendingContinuation(journal, new Set(screen.actions.map((action) => action.id)));
+        }
+        if (sorted.waiting) {
+            renderer.line("Waiting on an owner or admin of your Catalyst workspace:");
+            for (const action of theirs)
+                renderer.item("· ", sorted.text(action));
+            if (skipped.length) {
+                renderer.item("· ", `Steps only they can do: ${skipped.map((s) => title(s.id)).join(", ")}.`);
+                const base = deps.baseUrl?.();
+                const integrations = base
+                    ? new URL("/settings/connections", base).href
+                    : undefined;
+                if (integrations && !theirs.some((a) => a.text.includes(integrations)))
+                    renderer.item("· ", `They start at ${integrations}, the Integrations page.`);
+            }
+        }
+        // A step skipped with Ctrl-C is no action, but it is still to come: the line below names it.
+        if (screen.actions.length || skipped.length) {
+            const continuation = pendingContinuation(journal, 
+            // A step paused with Ctrl-C is still to come, so it stays in this line.
+            new Set([
+                ...sorted.live.map((action) => action.id),
+                ...skipped.map((s) => s.id),
+            ]));
             if (continuation)
                 renderer.line(continuation);
         }
@@ -246,7 +328,7 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             renderer.line("Catalyst is ready to work on your team's tickets.");
         if (deps.logPath?.())
             renderer.line(`Full log: ${deps.logPath()}`);
-        return screen;
+        return sorted;
     };
     const ui = {
         signal: abort.signal,
@@ -264,14 +346,16 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             machineChecks.clear();
             machineBlocked = false;
             stop();
+            // Signed in already, the header carries who and where, so the lines below would repeat it.
+            let identityShown = false;
             if (!introduced) {
                 if (renderer)
-                    renderer.brand("setup", deps.version);
+                    identityShown = renderer.brand("setup", deps.version, identity ? onboardHeaderIdentity(identity) : undefined);
                 else
                     prompts.intro("Catalyst setup", { output: streams.output });
                 introduced = true;
             }
-            if (identity !== undefined)
+            if (identity !== undefined && !identityShown)
                 for (const line of onboardIdentityLines(identity))
                     if (renderer)
                         renderer.line(line);
@@ -465,16 +549,35 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
         ...(prompts.multiselect
             ? {
                 async chooseRepositories(repositories) {
+                    const projectsPage = () => {
+                        try {
+                            const base = deps.baseUrl?.();
+                            return base ? ` (${new URL("/settings/projects", base).href})` : "";
+                        }
+                        catch {
+                            return "";
+                        }
+                    };
                     stop();
                     if (!repositories.length || abort.signal.aborted)
                         return null;
+                    // CTC-4742: what the team already uses starts selected. Unselecting never removes one.
+                    const selected = repositories
+                        .filter((row) => row.registered === true)
+                        .map((row) => `${row.owner}/${row.name}`);
                     const answer = await multiselect({
                         ...options,
-                        message: "Which repositories should use this Linear team?",
+                        message: selected.length
+                            ? `Which repositories should use this Linear team? Leaving a repository unselected does not remove it from this team; an admin removes one in Settings → Projects${projectsPage()}.`
+                            : "Which repositories should use this Linear team?",
                         required: true,
+                        ...(selected.length ? { initialValues: selected } : {}),
                         options: repositories.map((row) => ({
                             value: `${row.owner}/${row.name}`,
                             label: `${row.owner}/${row.name}`,
+                            ...(row.registered === false
+                                ? { hint: "not used by this team yet; selecting it adds it" }
+                                : {}),
                         })),
                     });
                     if (prompts.isCancel(answer)) {
@@ -558,9 +661,21 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             return typeof answer === "string" ? answer : null;
         },
         async chooseRunner() {
-            stop();
             if (abort.signal.aborted)
                 return null;
+            // CTC-4739: say what each answer does to this computer before asking, and how to skip it.
+            stop();
+            if (renderer) {
+                renderer.begin(number("runner"), title("runner"), "", "ask");
+                for (const line of RUNNER_EXPLAINED)
+                    renderer.detail(line);
+                active = true;
+                questionOpen = true;
+            }
+            else
+                prompts.log.message(RUNNER_EXPLAINED.join("\n"), {
+                    output: streams.output,
+                });
             const answer = await select({
                 ...options,
                 message: "Run Catalyst's work on this machine?",
@@ -586,25 +701,35 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
         async retryTimedOut(id) {
             if (abort.signal.aborted)
                 return false;
+            // The Connect accounts page does not expire: setup stopped waiting, and can wait again.
+            const page = connectWaits.has(id);
+            const why = page
+                ? "Setup stopped waiting for the Connect accounts page."
+                : "The link timed out.";
             if (renderer) {
                 // The question draws under this row, so the reason stays on screen while it is asked.
                 stop();
-                renderer.begin(number(id), title(id), "the link timed out", "ask");
+                renderer.begin(number(id), title(id), page ? "setup stopped waiting" : "the link timed out", "ask");
+                if (page)
+                    renderer.detail(why);
                 active = true;
                 questionOpen = true;
             }
             else {
                 stop();
-                prompts.log.message(`${title(id)}: the link timed out.`, {
+                prompts.log.message(`${title(id)}: ${why}`, {
                     output: streams.output,
                 });
             }
             const answer = await select({
                 ...options,
-                message: "Ready to try again?",
+                message: page ? "Keep waiting?" : "Ready to try again?",
                 initialValue: "again",
                 options: [
-                    { value: "again", label: "Yes, give me a new link" },
+                    {
+                        value: "again",
+                        label: page ? "Yes, keep waiting" : "Yes, give me a new link",
+                    },
                     { value: "stop", label: "Stop here. Run catalyst setup later to carry on." },
                 ],
             });
@@ -716,7 +841,7 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
                 }
                 if (step.id === "ready" || (hidden(step.id) && step.state !== "failed"))
                     return;
-                if ((step.id === "github.repos" || step.id === "settings") &&
+                if (step.id === "github.repos" &&
                     step.state === "done")
                     return;
                 if (step.id === "projects" &&
@@ -725,7 +850,7 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
                 const view = setupStepView(step, journal);
                 if (hidden(step.id))
                     enterPart(step.id);
-                renderer.step(view.mark, view.number, view.title, view.outcome);
+                renderer.step(view.mark, view.number, view.title, outcome(step, view));
                 const granted = deps.verbose ? onboardStepDetail(step) : undefined;
                 if (granted)
                     renderer.detail(granted);
@@ -772,7 +897,7 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             if (!renderer ||
                 !interactive ||
                 abort.signal.aborted ||
-                !setupFinalScreen(journal, deps.baseUrl?.()).actions.length)
+                !sortActions(journal).mine.length)
                 return false;
             active = false;
             summary(journal);
@@ -819,15 +944,14 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             }
             if (renderer) {
                 active = false;
-                const screen = summaryShown
-                    ? setupFinalScreen(journal, deps.baseUrl?.(), abort.signal.aborted)
-                    : summary(journal);
+                const sorted = summaryShown ? sortActions(journal) : summary(journal);
+                const { screen } = sorted;
                 if (summaryShown && screen.paused) {
                     renderer.heading(screen.heading);
                     renderer.line("Your progress is saved.");
                 }
                 summaryShown = false;
-                renderer.outro(say(screen.next));
+                renderer.outro(sorted.next);
                 return;
             }
             stop();
@@ -852,6 +976,19 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             prompts.outro(text, { output: streams.output });
         },
         async wait(text, run, page) {
+            if (currentStep && page) {
+                let path = "";
+                try {
+                    path = new URL(page.url).pathname;
+                }
+                catch {
+                    // Not a URL, so not the Connect accounts page.
+                }
+                if (path === CONNECT_PAGE_PATH)
+                    connectWaits.set(currentStep, page.url);
+                else
+                    connectWaits.delete(currentStep);
+            }
             const browser = currentStep && renderer && page
                 ? page
                 : currentStep &&

package/dist/onboard.js

@@ -45,16 +45,25 @@ function dailyUpdateChoice(value) {
         return { state: "skipped", reason: "no_scheduler" };
     return undefined;
 }
+const identityLabel = (text) => text
+    .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 180);
+/** CTC-4680: who and where for the lines beside setup's mark, "user: …" and "workspace: …". */
+export function onboardHeaderIdentity(identity) {
+    const display = identity.display;
+    return {
+        user: identityLabel(display?.email || display?.personLabel || identity.membershipId),
+        workspace: identityLabel(display?.workspaceName || identity.account),
+    };
+}
 export function onboardIdentityLines(identity) {
     if (!identity)
         return [
             "Use an existing Catalyst account or accept your invitation before approving sign-in.",
         ];
-    const label = (text) => text
-        .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, " ")
-        .replace(/\s+/g, " ")
-        .trim()
-        .slice(0, 180);
+    const label = identityLabel;
     const display = identity.display;
     const person = label(display?.personLabel || identity.membershipId);
     const email = display?.email ? label(display.email) : "";
@@ -591,7 +600,7 @@ function printPlan(ctx, journal, identity, options) {
             ctx.stdout(line);
     let group;
     // Beside --json and headless output: the numbers JSON actions carry (CTC-4680).
-    for (const row of standalonePlan(journal, options?.scope, options?.runner, "json")) {
+    for (const row of standalonePlan(journal, options?.scope, options?.runner, "json", options?.runnerDeclinedBy)) {
         if (row.group !== group) {
             ctx.stdout("");
             ctx.stdout(row.group);
@@ -788,7 +797,15 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
         for (const id of ONBOARD_STEPS)
             reviewedScope.add(id);
     const planOptions = (journal) => ({
-        runner: args.flags.runner === true,
+        runner: args.flags.runner === true
+            ? true
+            : args.flags["no-runner"] === true
+                ? false
+                : undefined,
+        // Headless turns --runner no and CATALYST_ONBOARD_RUNNER=no into --no-runner; say which.
+        runnerDeclinedBy: args.flags.headless === true
+            ? "the headless runner input is no"
+            : "--no-runner was passed",
         localSync: args.flags["local-sync"] === true || journal.localSync === true,
         scope: ONBOARD_STEPS.filter((id) => reviewedScope.has(id)),
     });

package/dist/setup-brand.js

@@ -0,0 +1,202 @@
+/** Ring order runs from the top tip, round the back, to the bottom tip, as in the brand script. */
+export const RING = [
+    [3, 0],
+    [2, 0],
+    [1, 0],
+    [0, 1],
+    [0, 2],
+    [1, 3],
+    [2, 3],
+    [3, 3],
+];
+export const CORE = [
+    [1, 1],
+    [2, 1],
+    [1, 2],
+    [2, 2],
+];
+export const MARK_SIZE = { dot: 3, gap: 1 };
+export const markSpan = (size = MARK_SIZE) => 4 * size.dot + 3 * size.gap;
+export const markLines = (size = MARK_SIZE) => Math.ceil(markSpan(size) / 2);
+const paintOf = (col, row) => RING.some(([c, r]) => c === col && r === row)
+    ? "ring"
+    : CORE.some(([c, r]) => c === col && r === row)
+        ? "core"
+        : null;
+/** The mark as a grid of square units, `markSpan` rows of half lines by `markSpan` columns. */
+export function markUnits(size = MARK_SIZE) {
+    const span = markSpan(size);
+    const pitch = size.dot + size.gap;
+    return Array.from({ length: span }, (_, y) => Array.from({ length: span }, (_, x) => x % pitch >= size.dot || y % pitch >= size.dot
+        ? null
+        : paintOf(Math.floor(x / pitch), Math.floor(y / pitch))));
+}
+const BRAND = {
+    ink: "#11100e",
+    cream: "#f1ebe2",
+    copper: "#d28e63",
+    rust: "#a9512f",
+};
+/** The brand rules: a cream C and copper core on dark, an ink C and rust core on light. */
+const PALETTES = {
+    dark: { ring: BRAND.cream, core: BRAND.copper },
+    light: { ring: BRAND.ink, core: BRAND.rust },
+};
+export function colourLevel(env, terminal) {
+    if (terminal.noColor)
+        return "none";
+    const force = env.FORCE_COLOR;
+    if (force !== undefined) {
+        if (force === "0" || force === "false")
+            return "none";
+        if (force === "" || force === "1" || force === "true")
+            return "16";
+        if (force === "2")
+            return "256";
+        if (force === "3")
+            return "truecolor";
+    }
+    if (env.NO_COLOR !== undefined || !terminal.tty)
+        return "none";
+    if (!env.TERM || env.TERM === "dumb")
+        return "none";
+    if (/^(truecolor|24bit)$/i.test(env.COLORTERM ?? ""))
+        return "truecolor";
+    return /256/.test(env.TERM) ? "256" : "16";
+}
+/** CI as most tools read it: set, and not "", "0" or "false". */
+export function inCi(env) {
+    return ![undefined, "", "0", "false"].includes(env.CI);
+}
+export const MARK_MIN_COLUMNS = 60;
+/**
+ * Why the mark is left off, or null to draw it. Off for every verb but setup, without a terminal,
+ * in CI, with --no-color or NO_COLOR or no colour at all, without UTF-8 (the blocks are UTF-8), and
+ * below 60 columns. The text lines are printed either way.
+ */
+export function markSkipped(options) {
+    const { env } = options;
+    if (!options.setup)
+        return "not catalyst setup";
+    if (!options.tty)
+        return "not a terminal";
+    if (inCi(env))
+        return "CI";
+    if (options.noColor)
+        return "--no-color";
+    if (env.NO_COLOR !== undefined)
+        return "NO_COLOR";
+    if (colourLevel(env, options) === "none")
+        return "no colour";
+    if (!/utf-?8/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || ""))
+        return "not UTF-8";
+    if (options.columns < MARK_MIN_COLUMNS)
+        return "narrow";
+    return null;
+}
+const rgb = (hex) => [
+    Number.parseInt(hex.slice(1, 3), 16),
+    Number.parseInt(hex.slice(3, 5), 16),
+    Number.parseInt(hex.slice(5, 7), 16),
+];
+const distance = (a, b) => (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2;
+/** The nearest xterm-256 colour: the 6×6×6 cube or the 24-step grey ramp, whichever is closer. */
+export function nearest256(hex) {
+    const colour = rgb(hex);
+    const levels = [0, 95, 135, 175, 215, 255];
+    const step = (v) => levels.reduce((best, l, i) => (Math.abs(l - v) < Math.abs(levels[best] - v) ? i : best), 0);
+    const [ri, gi, bi] = colour.map(step);
+    const avg = (colour[0] + colour[1] + colour[2]) / 3;
+    const greyIndex = Math.min(23, Math.max(0, Math.round((avg - 8) / 10)));
+    const grey = 8 + 10 * greyIndex;
+    return distance([levels[ri], levels[gi], levels[bi]], colour) <=
+        distance([grey, grey, grey], colour)
+        ? 16 + 36 * ri + 6 * gi + bi
+        : 232 + greyIndex;
+}
+/** xterm's default 16 colours, as SGR foreground codes. */
+const XTERM16 = [
+    [30, [0, 0, 0]],
+    [31, [205, 0, 0]],
+    [32, [0, 205, 0]],
+    [33, [205, 205, 0]],
+    [34, [0, 0, 238]],
+    [35, [205, 0, 205]],
+    [36, [0, 205, 205]],
+    [37, [229, 229, 229]],
+    [90, [127, 127, 127]],
+    [91, [255, 0, 0]],
+    [92, [0, 255, 0]],
+    [93, [255, 255, 0]],
+    [94, [92, 92, 255]],
+    [95, [255, 0, 255]],
+    [96, [0, 255, 255]],
+    [97, [255, 255, 255]],
+];
+/**
+ * The nearest of xterm's 16 default colours. Plain distance puts copper nearest grey (90), and the
+ * core is the mark's one accent, so the core picks from the coloured entries only: copper is then
+ * yellow (33) and rust red (31). The ring takes plain distance: cream is white (37), ink black (30).
+ */
+export function nearest16(hex, accent = false) {
+    const colour = rgb(hex);
+    const greys = [30, 37, 90, 97];
+    return XTERM16.filter(([code]) => !accent || !greys.includes(code)).reduce((best, entry) => distance(entry[1], colour) < distance(best[1], colour) ? entry : best)[0];
+}
+/**
+ * The SGR parameters for one of the mark's colours on a `theme` background, as a foreground or a
+ * background. With 16 colours the core is also bold, which most terminals draw brighter.
+ */
+export function markColour(paint, theme, level, layer = "fg") {
+    const hex = PALETTES[theme][paint];
+    const lead = layer === "fg" ? 38 : 48;
+    if (level === "truecolor")
+        return `${lead};2;${rgb(hex).join(";")}`;
+    if (level === "256")
+        return `${lead};5;${nearest256(hex)}`;
+    const code = nearest16(hex, paint === "core") + (layer === "fg" ? 0 : 10);
+    return paint === "core" && layer === "fg" ? `1;${code}` : String(code);
+}
+/**
+ * Units to terminal lines, two unit rows per line: both halves set is a full block (or an upper
+ * half block on the lower colour's background when they differ), one half is a half block, neither
+ * is a space. Each run of one glyph colour is closed with a reset.
+ */
+export function unitLines(units, theme, level) {
+    const lines = [];
+    for (let y = 0; y < units.length; y += 2) {
+        const upper = units[y];
+        const lower = units[y + 1] ?? [];
+        let out = "";
+        let open = "";
+        for (let x = 0; x < upper.length; x++) {
+            const [top, bottom] = [upper[x] ?? null, lower[x] ?? null];
+            const sgr = top && bottom && top !== bottom
+                ? `${markColour(top, theme, level)};${markColour(bottom, theme, level, "bg")}`
+                : top || bottom
+                    ? markColour((top ?? bottom), theme, level)
+                    : "";
+            if (sgr !== open) {
+                if (open)
+                    out += "\u001b[0m";
+                if (sgr)
+                    out += `\u001b[${sgr}m`;
+                open = sgr;
+            }
+            out +=
+                !top && !bottom
+                    ? " "
+                    : top && bottom && top === bottom
+                        ? "█"
+                        : top
+                            ? "▀"
+                            : "▄";
+        }
+        lines.push(open ? `${out}\u001b[0m` : out);
+    }
+    return lines;
+}
+/** The mark, one string per terminal line: `markLines` lines of `markSpan` columns. */
+export function pixelNucleusLines(theme, level, size = MARK_SIZE) {
+    return unitLines(markUnits(size), theme, level);
+}