feat(share): copy a link that opens your config

Dotfiles get passed around, and until now the only way to hand someone a
config was to send them the file and have them import it.

The config goes in the fragment, which browsers do not send, so a link
reaches whoever opens it without touching a server here: nothing is
stored, there is no id to look up, and no link can expire or be taken
back. Only what differs from Kitty's defaults goes in, deflated, which
puts a full theme plus a page of settings comfortably inside the length
anything will carry.

Opening a link replaces what was already there, so it goes through the
store as one step and undo puts the previous work back. A link is
something somebody else wrote, so it goes through the same sanitiser as
an imported file, and anything not shaped like a config is ignored rather
than sanitised into an empty one, which would have quietly cleared the
editor.

Pasting a link into a tab that already has the editor open only changes
the fragment and reloads nothing, so that is handled too.

Author: xcutiboo

README.md

@@ -58,6 +58,12 @@ the editor. Anything it does not model, whether that is a kitten, an `include`
 line, `env`, or an option from a Kitty newer than it knows about, is kept
 verbatim and written back out.
 
+**Share** copies a link that opens your config in somebody else's browser. The
+config rides in the fragment, the part of a URL browsers never send, so it
+reaches them without touching a server here: there is nothing stored, no id to
+look up, and no link to expire. Opening one replaces what you had, which undo
+puts back.
+
 Pick your Kitty version, anywhere from 0.15 to 0.48, and options that release
 does not have are commented out with the version that introduced them instead of
 being emitted silently.

src/app/app.component.ts

@@ -2,6 +2,7 @@ import { CommonModule } from "@angular/common";
 import {
 	afterNextRender,
 	Component,
+	DestroyRef,
 	HostListener,
 	inject,
 	signal,
@@ -11,6 +12,7 @@ import { CategoryNavigationComponent } from "../components/category-navigation/c
 import { ConfigEditorComponent } from "../components/config-editor/config-editor.component";
 import { HeaderComponent } from "../components/header/header.component";
 import { LivePreviewComponent } from "../components/live-preview/live-preview.component";
+import { ConfigSharingService } from "../services/config-sharing.service";
 import { ConfigStoreService } from "../services/config-store.service";
 import { formatCount, SiteStatsService } from "../services/site-stats.service";
 
@@ -43,6 +45,32 @@ function isTextEntry(target: EventTarget | null): boolean {
     <div class="h-dvh bg-kitty-darker text-kitty-text flex flex-col overflow-hidden">
       <app-header (aboutRequested)="showAbout.set(true)" />
 
+      <!--
+        Says plainly that what is on screen replaced what was here, and how to
+        get it back, because the swap happens before anyone has touched anything.
+      -->
+      @if (openedFromLink()) {
+        <div
+          class="px-3 sm:px-4 lg:px-6 py-2 border-b border-kitty-border bg-kitty-surface-light/60 flex items-center gap-3 text-sm text-kitty-text-dim"
+          role="status"
+        >
+          <span class="flex-1 min-w-0">
+            Opened from a shared link. Nothing was uploaded; the config travelled
+            in the address. Undo to go back to your own.
+          </span>
+          <button
+            type="button"
+            (click)="openedFromLink.set(false)"
+            class="flex-shrink-0 -m-1.5 p-1.5 opacity-70 hover:opacity-100 transition-opacity"
+            aria-label="Dismiss message"
+          >
+            <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
+              <path d="M6 18L18 6M6 6l12 12"/>
+            </svg>
+          </button>
+        </div>
+      }
+
       @if (showAbout()) {
         <app-about-modal (closeRequested)="showAbout.set(false)" />
       }
@@ -137,10 +165,48 @@ export class AppComponent {
 	readonly visitors = this.siteStats.visitors;
 	readonly format = formatCount;
 
+	private readonly sharing = inject(ConfigSharingService);
+	/** Says where the config came from, since nothing else on screen would. */
+	readonly openedFromLink = signal(false);
+
 	constructor() {
 		// After the first paint, so a slow or blocked request never delays the
 		// editor appearing.
 		afterNextRender(() => void this.siteStats.load());
+		afterNextRender(() => void this.openSharedConfig());
+
+		// Pasting a link into the address bar of a tab that already has the editor
+		// open only changes the fragment, so nothing reloads and none of the above
+		// runs again. Without this the link appears to do nothing at all.
+		const onHashChange = () => void this.openSharedConfig();
+		globalThis.addEventListener("hashchange", onHashChange);
+		inject(DestroyRef).onDestroy(() =>
+			globalThis.removeEventListener("hashchange", onHashChange),
+		);
+	}
+
+	/**
+	 * Opens a config someone was sent a link to. It replaces whatever was
+	 * restored from the last visit, which is why it goes through the store as a
+	 * single step: Ctrl+Z puts the previous work straight back.
+	 *
+	 * The fragment is cleared afterwards so that editing from here does not leave
+	 * an address bar describing a config that is no longer the one on screen.
+	 */
+	private async openSharedConfig(): Promise<void> {
+		const hash = globalThis.location.hash;
+		if (!hash.includes("c=")) return;
+
+		const shared = await this.sharing.fromHash(hash);
+		if (!shared) return;
+
+		this.configStore.loadConfig(shared);
+		this.openedFromLink.set(true);
+		globalThis.history.replaceState(
+			null,
+			"",
+			globalThis.location.pathname + globalThis.location.search,
+		);
 	}
 
 	/**

src/components/header/header.component.ts

@@ -2,6 +2,7 @@ import { CommonModule } from "@angular/common";
 import { Component, computed, inject, output, signal } from "@angular/core";
 import { FormsModule } from "@angular/forms";
 import { DEFAULT_KITTY_CONFIG, SEARCHABLE_OPTION_COUNT } from "../../models/kitty-defaults";
+import { ConfigSharingService } from "../../services/config-sharing.service";
 import { ConfigStoreService } from "../../services/config-store.service";
 import { KittyGeneratorService } from "../../services/kitty-generator.service";
 import { KittyParserService } from "../../services/kitty-parser.service";
@@ -235,6 +236,18 @@ function countDirectives(config: KittyConfigAST): number {
           {{ configStore.advancedMode() ? 'Advanced' : 'Simple' }}
         </button>
 
+        <button
+          (click)="handleShare()"
+          class="hidden sm:flex items-center gap-2 px-3 py-2 lg:px-4 lg:py-2.5 bg-kitty-surface-light hover:bg-kitty-bg text-kitty-text rounded-lg text-sm font-medium transition-colors border border-kitty-border"
+          title="Copy a link that opens this config"
+        >
+          <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M10 13a5 5 0 007.54.54l3-3a5 5 0 00-7.07-7.07l-1.72 1.71"/>
+            <path d="M14 11a5 5 0 00-7.54-.54l-3 3a5 5 0 007.07 7.07l1.71-1.71"/>
+          </svg>
+          <span class="hidden xl:inline">Share</span>
+        </button>
+
         <button
           (click)="handleImport()"
           class="hidden sm:flex items-center gap-2 px-3 py-2 lg:px-4 lg:py-2.5 bg-kitty-surface-light hover:bg-kitty-bg text-kitty-text rounded-lg text-sm font-medium transition-colors border border-kitty-border"
@@ -329,6 +342,10 @@ function countDirectives(config: KittyConfigAST): number {
             <svg class="w-4 h-4 text-kitty-text-dim" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2"><rect x="2" y="3" width="20" height="14" rx="2"/><line x1="8" y1="21" x2="16" y2="21"/><line x1="12" y1="17" x2="12" y2="21"/></svg>
             {{ configStore.previewVisible() ? 'Hide Preview' : 'Show Preview' }}
           </button>
+          <button (click)="handleShare(); mobileMenuOpen.set(false)" class="w-full px-3 py-2.5 rounded-lg text-left text-sm text-kitty-text hover:bg-kitty-surface-light transition-all duration-150 flex items-center gap-3 active:scale-[0.98]">
+            <svg class="w-4 h-4 text-kitty-text-dim" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10 13a5 5 0 007.54.54l3-3a5 5 0 00-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 00-7.54-.54l-3 3a5 5 0 007.07 7.07l1.71-1.71"/></svg>
+            Copy Share Link
+          </button>
           <button (click)="handleImport(); mobileMenuOpen.set(false)" class="w-full px-3 py-2.5 rounded-lg text-left text-sm text-kitty-text hover:bg-kitty-surface-light transition-all duration-150 flex items-center gap-3 active:scale-[0.98]">
             <svg class="w-4 h-4 text-kitty-text-dim" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2"><path d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-8l-4-4m0 0L8 8m4-4v12"/></svg>
             Import Config
@@ -459,6 +476,7 @@ export class HeaderComponent {
 		public readonly themeService: ThemeService,
 		private readonly generator: KittyGeneratorService,
 		private readonly parser: KittyParserService,
+		private readonly sharing: ConfigSharingService,
 	) {}
 
 	handleImport(): void {
@@ -507,4 +525,40 @@ export class HeaderComponent {
 	handleExport(): void {
 		this.generator.downloadConfig(this.configStore.configState());
 	}
+
+	/**
+	 * The config travels in the link's fragment, so it is never sent anywhere:
+	 * whoever opens it decodes it in their own browser. Nothing is stored here,
+	 * which also means a link cannot be taken back once it is sent.
+	 */
+	async handleShare(): Promise<void> {
+		const link = await this.sharing.toLink(
+			this.configStore.configState(),
+			`${globalThis.location.origin}${globalThis.location.pathname}`,
+		);
+
+		if (!link) {
+			this.importStatus.set({
+				tone: "error",
+				message: "This config is too large to put in a link. Export the file instead.",
+			});
+			return;
+		}
+
+		try {
+			await navigator.clipboard.writeText(link);
+			this.importStatus.set({
+				tone: "success",
+				message: "Link copied. It carries your config in the address itself, so nothing was uploaded.",
+			});
+		} catch {
+			// Denied clipboard permission, or an insecure origin. Putting the link
+			// in the address bar at least leaves it somewhere copyable.
+			globalThis.location.hash = new URL(link).hash;
+			this.importStatus.set({
+				tone: "success",
+				message: "Link ready in the address bar; copying it was blocked by the browser.",
+			});
+		}
+	}
 }

src/services/config-sharing.service.spec.ts

@@ -0,0 +1,141 @@
+import { TestBed } from "@angular/core/testing";
+import { beforeEach, describe, expect, it } from "vitest";
+import { DEFAULT_KITTY_CONFIG } from "../models/kitty-defaults";
+import type { KittyConfigAST } from "../models/kitty-types";
+import { ConfigSharingService } from "./config-sharing.service";
+
+const BASE = "https://confitty.app/";
+
+describe("ConfigSharingService", () => {
+	let sharing: ConfigSharingService;
+
+	beforeEach(() => {
+		TestBed.resetTestingModule();
+		sharing = TestBed.inject(ConfigSharingService);
+	});
+
+	function edited(change: (config: KittyConfigAST) => void): KittyConfigAST {
+		const config = structuredClone(DEFAULT_KITTY_CONFIG);
+		change(config);
+		return config;
+	}
+
+	async function roundTrip(config: KittyConfigAST): Promise<KittyConfigAST> {
+		const link = await sharing.toLink(config, BASE);
+		expect(link).not.toBeNull();
+		const restored = await sharing.fromHash(new URL(link ?? "").hash);
+		expect(restored).not.toBeNull();
+		return restored as KittyConfigAST;
+	}
+
+	it("brings a config back out of its own link", async () => {
+		const config = edited((c) => {
+			c.fonts.font_family = "JetBrains Mono";
+			c.fonts.font_size = 15;
+			c.colors.background = "#101010";
+			c.keyboard_shortcuts = [{ chord: "ctrl+shift+t", action: "new_tab" }];
+		});
+
+		expect(await roundTrip(config)).toEqual(config);
+	});
+
+	it("keeps the whole palette a theme wrote", async () => {
+		const config = edited((c) => {
+			for (let i = 0; i < 16; i++) {
+				(c.colors as unknown as Record<string, string>)[`color${i}`] =
+					`#${i.toString(16).repeat(6)}`;
+			}
+		});
+
+		expect((await roundTrip(config)).colors).toEqual(config.colors);
+	});
+
+	it("puts the config in the fragment, where a server never sees it", async () => {
+		const link =
+			(await sharing.toLink(
+				edited((c) => {
+					c.fonts.font_size = 20;
+				}),
+				BASE,
+			)) ?? "";
+
+		const url = new URL(link);
+		expect(url.search).toBe("");
+		expect(url.pathname).toBe("/");
+		expect(url.hash.startsWith("#c=")).toBe(true);
+	});
+
+	it("keeps a link short enough to paste", async () => {
+		// Everything a theme touches plus a page of settings, which is the
+		// heaviest thing anybody shares in practice.
+		const config = edited((c) => {
+			for (let i = 0; i < 16; i++) {
+				(c.colors as unknown as Record<string, string>)[`color${i}`] =
+					`#a${i.toString(16)}b1c2`;
+			}
+			c.colors.background = "#101010";
+			c.colors.foreground = "#e0e0e0";
+			c.fonts.font_family = "JetBrains Mono";
+			c.fonts.font_size = 13;
+			c.scrollback.scrollback_lines = 20000;
+			c.keyboard_shortcuts = Array.from({ length: 10 }, (_, i) => ({
+				chord: `ctrl+shift+f${i}`,
+				action: `goto_tab ${i}`,
+			}));
+		});
+
+		const link = (await sharing.toLink(config, BASE)) ?? "";
+		expect(link.length).toBeLessThan(2000);
+	});
+
+	it("carries only what was changed", async () => {
+		const untouched = (await sharing.toLink(DEFAULT_KITTY_CONFIG, BASE)) ?? "";
+		const oneField =
+			(await sharing.toLink(
+				edited((c) => {
+					c.fonts.font_size = 20;
+				}),
+				BASE,
+			)) ?? "";
+
+		expect(untouched.length).toBeLessThan(oneField.length);
+		expect(await sharing.fromHash(new URL(untouched).hash)).toEqual(
+			DEFAULT_KITTY_CONFIG,
+		);
+	});
+
+	it.each([
+		["no fragment at all", ""],
+		["a fragment about something else", "#section=fonts"],
+		["an empty payload", "#c="],
+		["a payload that is not base64", "#c=1!!!!not base64!!!!"],
+		["a payload cut in half", "#c=1eJyrVkrLz1eyUkq"],
+		["a marker nobody wrote", "#c=9abcdef"],
+		["base64 that is not a config", `#c=0${btoa("hello there")}`],
+		["base64 of JSON that is not one", `#c=0${btoa('["a","b"]')}`],
+	])("returns nothing for %s", async (_label, hash) => {
+		expect(await sharing.fromHash(hash)).toBeNull();
+	});
+
+	it("sanitises a link the way it sanitises an imported file", async () => {
+		// A link is written by somebody else, so it gets no more trust than a file.
+		const hostile = btoa(
+			JSON.stringify({
+				__proto__: { polluted: "yes" },
+				fonts: { font_size: "enormous", not_an_option: 1 },
+			}),
+		);
+
+		const restored = (await sharing.fromHash(`#c=0${hostile}`)) as unknown as {
+			fonts: Record<string, unknown>;
+		};
+
+		expect(({} as Record<string, unknown>)["polluted"]).toBeUndefined();
+		expect(typeof restored.fonts["font_size"]).toBe("number");
+		expect(restored.fonts["not_an_option"]).toBeUndefined();
+	});
+
+	it("refuses a fragment far larger than any config", async () => {
+		expect(await sharing.fromHash(`#c=0${"A".repeat(30_000)}`)).toBeNull();
+	});
+});