feat: add shareable configuration URLs

index.html

@@ -94,6 +94,7 @@
           </div>
 
           <button id="export" class="export-button">Render 4K PNG</button>
+          <button id="share" class="share-button" type="button">Copy share URL</button>
           <p id="export-status" class="export-status" role="status">Rendered locally in your browser.</p>
         </aside>
 

src/main.ts

@@ -2,6 +2,7 @@ import "./style.css";
 import logoSvg from "../assets/hugging-face.svg?raw";
 import { generateLayout, type LayoutOptions } from "./layout";
 import { renderWallpaper, type WallpaperSymbol } from "./render";
+import { decodeShareState, encodeShareState, type ShareState } from "./url-state";
 
 interface Config extends LayoutOptions {
   width: number;
@@ -34,6 +35,7 @@ const spacingInput = element<HTMLInputElement>("spacing");
 const rotationInput = element<HTMLInputElement>("rotation");
 const seedInput = element<HTMLInputElement>("seed");
 const exportButton = element<HTMLButtonElement>("export");
+const shareButton = element<HTMLButtonElement>("share");
 const exportStatus = element<HTMLParagraphElement>("export-status");
 const renderStats = element<HTMLSpanElement>("render-stats");
 
@@ -111,6 +113,58 @@ function readConfig(): Config {
   };
 }
 
+function currentShareState(config = readConfig()): ShareState {
+  return {
+    width: config.width,
+    height: config.height,
+    symbol: symbolMode === "logo" ? "hf" : selectedEmoji,
+    density: config.count,
+    size: config.logoScale,
+    variation: config.sizeVariation,
+    spacing: config.spacing,
+    rotation: config.rotation,
+    seed: config.seed,
+  };
+}
+
+function canonicalUrl(config = readConfig()): URL {
+  const url = new URL(window.location.href);
+  url.search = encodeShareState(currentShareState(config));
+  url.hash = "";
+  return url;
+}
+
+function syncUrl(config: Config): void {
+  window.history.replaceState(null, "", canonicalUrl(config));
+}
+
+function restoreFromUrl(): void {
+  const state = decodeShareState(window.location.search);
+  if (state.width !== undefined && state.height !== undefined) {
+    widthInput.value = String(state.width);
+    heightInput.value = String(state.height);
+    const preset = `${state.width}x${state.height}`;
+    resolution.value = [...resolution.options].some((option) => option.value === preset) ? preset : "custom";
+  }
+  if (state.symbol !== undefined) {
+    if (state.symbol === "hf") setSymbolMode("logo");
+    else {
+      selectedEmoji = state.symbol;
+      selectedEmojiElement.textContent = selectedEmoji;
+      modeEmoji.textContent = selectedEmoji;
+      selectedEmojiName.textContent = "Emoji from URL";
+      setSymbolMode("emoji");
+    }
+  }
+  if (state.density !== undefined) densityInput.value = String(state.density);
+  if (state.size !== undefined) sizeInput.value = String(state.size);
+  if (state.variation !== undefined) sizeVariationInput.value = String(state.variation);
+  if (state.spacing !== undefined) spacingInput.value = String(state.spacing);
+  if (state.rotation !== undefined) rotationInput.value = String(state.rotation);
+  if (state.seed !== undefined) seedInput.value = String(state.seed);
+  schedulePreview();
+}
+
 function configKey(config: Config): string {
   return [config.aspect.toFixed(6), config.count, config.logoScale, config.sizeVariation, config.spacing, config.rotation, config.seed].join(":");
 }
@@ -138,6 +192,7 @@ function renderPreview(): void {
     currentConfigKey = key;
   }
   updateLabels(config);
+  syncUrl(config);
 
   const bounds = canvasWrap.getBoundingClientRect();
   const cssWidth = Math.max(320, bounds.width);
@@ -208,6 +263,30 @@ async function exportPng(): Promise<void> {
   }
 }
 
+async function copyShareUrl(): Promise<void> {
+  const url = canonicalUrl();
+  syncUrl(readConfig());
+  try {
+    if (navigator.clipboard?.writeText) await navigator.clipboard.writeText(url.href);
+    else {
+      const textarea = document.createElement("textarea");
+      textarea.value = url.href;
+      textarea.style.position = "fixed";
+      textarea.style.opacity = "0";
+      document.body.append(textarea);
+      textarea.select();
+      document.execCommand("copy");
+      textarea.remove();
+    }
+    shareButton.textContent = "URL copied";
+  } catch {
+    shareButton.textContent = "Copy failed — use address bar";
+  }
+  window.setTimeout(() => {
+    shareButton.textContent = "Copy share URL";
+  }, 1800);
+}
+
 function setDefaults(): void {
   resolution.value = "3840x2160";
   widthInput.value = "3840";
@@ -266,8 +345,11 @@ element<HTMLButtonElement>("randomize").addEventListener("click", () => {
 });
 element<HTMLButtonElement>("reset").addEventListener("click", setDefaults);
 exportButton.addEventListener("click", () => void exportPng());
+shareButton.addEventListener("click", () => void copyShareUrl());
 new ResizeObserver(schedulePreview).observe(canvasWrap);
 
+restoreFromUrl();
+
 const logoImage = new Image();
 const logoUrl = URL.createObjectURL(new Blob([logoSvg], { type: "image/svg+xml" }));
 logoImage.decoding = "async";

src/style.css

@@ -53,6 +53,8 @@ input[type="range"] { width: 100%; margin: 0; cursor: ew-resize; }
 .export-button { width: 100%; border: 0; border-radius: 12px; margin-top: 18px; padding: 12px 16px; color: #2d2706; font-weight: 850; cursor: pointer; background: linear-gradient(135deg, #ffd21e, #ffad03); box-shadow: 0 8px 22px rgba(255,173,3,0.25); }
 .export-button:hover { filter: brightness(1.03); transform: translateY(-1px); }
 .export-button:disabled { cursor: wait; opacity: 0.65; transform: none; }
+.share-button { width: 100%; margin-top: 8px; padding: 10px 14px; border: 1px solid #b9d2df; border-radius: 11px; color: #23536f; background: #eef7fb; cursor: pointer; font-size: 0.78rem; font-weight: 800; }
+.share-button:hover { border-color: #0d82df; color: #0d73c7; background: #e5f4fc; }
 .export-status { min-height: 2.4em; margin: 9px 2px 0; color: #718894; font-size: 0.72rem; line-height: 1.35; }
 
 .preview-panel { overflow: hidden; border-radius: 20px; }

src/url-state.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { decodeShareState, DEFAULT_SHARE_STATE, encodeShareState, type ShareState } from "./url-state";
+
+describe("share URLs", () => {
+  it("keeps the default URL clean", () => {
+    expect(encodeShareState(DEFAULT_SHARE_STATE)).toBe("");
+  });
+
+  it("uses readable names and compact values", () => {
+    const state: ShareState = {
+      width: 5120,
+      height: 2880,
+      symbol: "🦋",
+      density: 160,
+      size: 1.2,
+      variation: 0.8,
+      spacing: 1.1,
+      rotation: 35,
+      seed: 42,
+    };
+    expect(decodeShareState(encodeShareState(state))).toEqual(state);
+    expect(decodeURIComponent(encodeShareState(state))).toBe(
+      "canvas=5k&symbol=🦋&density=160&size=1.2&variation=0.8&spacing=1.1&rotation=35&seed=42",
+    );
+  });
+
+  it("supports custom canvas sizes and joined emoji", () => {
+    expect(decodeShareState("?canvas=1440x900&symbol=👨‍👩‍👧‍👦")).toEqual({
+      width: 1440,
+      height: 900,
+      symbol: "👨‍👩‍👧‍👦",
+    });
+  });
+
+  it("ignores unknown and out-of-range values", () => {
+    expect(decodeShareState("?canvas=10x10&density=900&size=nope&other=1")).toEqual({});
+  });
+});

src/url-state.ts

@@ -0,0 +1,106 @@
+export interface ShareState {
+  width: number;
+  height: number;
+  symbol: string;
+  density: number;
+  size: number;
+  variation: number;
+  spacing: number;
+  rotation: number;
+  seed: number;
+}
+
+export const DEFAULT_SHARE_STATE: ShareState = {
+  width: 3840,
+  height: 2160,
+  symbol: "hf",
+  density: 88,
+  size: 1,
+  variation: 1,
+  spacing: 1,
+  rotation: 52,
+  seed: 84237,
+};
+
+const CANVAS_ALIASES = new Map<string, readonly [number, number]>([
+  ["1080p", [1920, 1080]],
+  ["1440p", [2560, 1440]],
+  ["4k", [3840, 2160]],
+  ["5k", [5120, 2880]],
+  ["8k", [7680, 4320]],
+]);
+
+const CANVAS_NAMES = new Map([...CANVAS_ALIASES].map(([name, dimensions]) => [`${dimensions[0]}x${dimensions[1]}`, name]));
+
+function compactNumber(value: number): string {
+  return String(Number(value.toFixed(2)));
+}
+
+function firstGrapheme(value: string): string | undefined {
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+  return segmenter.segment(trimmed)[Symbol.iterator]().next().value?.segment;
+}
+
+function readNumber(params: URLSearchParams, name: string, minimum: number, maximum: number, integer = false): number | undefined {
+  const raw = params.get(name);
+  if (raw === null || raw.trim() === "") return undefined;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < minimum || parsed > maximum) return undefined;
+  return integer ? Math.round(parsed) : Math.round(parsed * 100) / 100;
+}
+
+function readCanvas(value: string | null): readonly [number, number] | undefined {
+  if (!value) return undefined;
+  const alias = CANVAS_ALIASES.get(value.toLowerCase());
+  if (alias) return alias;
+  const match = /^(\d{3,4})x(\d{3,4})$/i.exec(value);
+  if (!match) return undefined;
+  const width = Number(match[1]);
+  const height = Number(match[2]);
+  if (width < 640 || width > 7680 || height < 360 || height > 4320) return undefined;
+  return [width, height];
+}
+
+export function encodeShareState(state: ShareState): string {
+  const params = new URLSearchParams();
+  if (state.width !== DEFAULT_SHARE_STATE.width || state.height !== DEFAULT_SHARE_STATE.height) {
+    const dimensions = `${state.width}x${state.height}`;
+    params.set("canvas", CANVAS_NAMES.get(dimensions) ?? dimensions);
+  }
+  if (state.symbol !== DEFAULT_SHARE_STATE.symbol) params.set("symbol", state.symbol);
+  if (state.density !== DEFAULT_SHARE_STATE.density) params.set("density", String(Math.round(state.density)));
+  if (state.size !== DEFAULT_SHARE_STATE.size) params.set("size", compactNumber(state.size));
+  if (state.variation !== DEFAULT_SHARE_STATE.variation) params.set("variation", compactNumber(state.variation));
+  if (state.spacing !== DEFAULT_SHARE_STATE.spacing) params.set("spacing", compactNumber(state.spacing));
+  if (state.rotation !== DEFAULT_SHARE_STATE.rotation) params.set("rotation", String(Math.round(state.rotation)));
+  if (state.seed !== DEFAULT_SHARE_STATE.seed) params.set("seed", String(Math.round(state.seed) >>> 0));
+  return params.toString();
+}
+
+export function decodeShareState(search: string): Partial<ShareState> {
+  const params = new URLSearchParams(search);
+  const state: Partial<ShareState> = {};
+  const canvas = readCanvas(params.get("canvas"));
+  if (canvas) [state.width, state.height] = canvas;
+
+  const symbol = params.get("symbol");
+  if (symbol === "hf") state.symbol = "hf";
+  else if (symbol) {
+    const emoji = firstGrapheme(symbol);
+    if (emoji) state.symbol = emoji;
+  }
+
+  state.density = readNumber(params, "density", 24, 512, true);
+  state.size = readNumber(params, "size", 0.5, 1.6);
+  state.variation = readNumber(params, "variation", 0, 1.5);
+  state.spacing = readNumber(params, "spacing", 0.25, 2);
+  state.rotation = readNumber(params, "rotation", 0, 70, true);
+  state.seed = readNumber(params, "seed", 0, 4294967295, true);
+
+  for (const key of Object.keys(state) as (keyof ShareState)[]) {
+    if (state[key] === undefined) delete state[key];
+  }
+  return state;
+}