Share my setup, model: one file or one waybetter://setup link with the look (theme id, accent, icon pack), the mode and the non-default flags, nothing personal; reading drops what the app does not know and refuses another app's setup; the plan lists exactly what would change and applying it changes nothing else (not in the UI yet)

This commit is contained in:
CRTkafa 2026-10-01 04:38:30 +07:00
parent edc3655b2a
commit 2c7c143487
2 changed files with 309 additions and 0 deletions

View file

@ -0,0 +1,173 @@
// "Share my setup": one small file or one `waybetter://setup?…` link that carries how the app looks
// and what it does, never who uses it. It holds exactly four things: the theme (its id, the accent
// and the icon pack), the mode, and the feature flags that differ from the app's defaults. Nothing
// else can ride along: no account, profile, note, draft, starred message, keyword, workspace, custom
// CSS or theme file (a theme is named by id, so a theme only the sender has stays theirs).
//
// Importing never applies on its own: `setupPlan` says what would change (and what cannot, such as
// a theme that is not installed here), and the panel asks before `applySetup` writes anything.
// Pure: unit-tested in tests/setup.test.ts, used by panel/ShareSetup.tsx.
import { modeById, normalizeFlags, sparseFlags, type FeatureTable, type Flags } from '../../../runtime/src/featureTable.ts';
export const SETUP_FORMAT = 'waybetter-setup';
export const SETUP_VERSION = 1;
/** The link's scheme and path: `waybetter://setup?app=<app>&d=<data>`. */
export const SETUP_LINK = 'waybetter://setup';
/** A setup is a few hundred bytes; anything much larger is not one. */
export const SETUP_MAX_BYTES = 16 * 1024;
export const SETUP_FILE_SUFFIX = '.waybetter-setup.json';
const ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
const COLOR = /^#[0-9a-f]{6}$/i;
/** The look: a theme by id, its accent, the icon pack (absent: the theme's own). */
export type SetupTheme = { preset: string; accent: string | null; icons?: string };
export type SharedSetup = {
format: typeof SETUP_FORMAT;
version: typeof SETUP_VERSION;
/** The app it is for ("x"): a setup never applies to another app. */
app: string;
theme?: SetupTheme;
/** The mode it started from (null: none chosen). */
mode?: string | null;
/** Feature flags that differ from the app's defaults (the rest are the defaults). */
flags: Flags;
};
/** What the app has now, in the terms a setup speaks. */
export type SetupState = { theme?: SetupTheme; mode: string | null; flags: Flags };
/** The setup of `state`: only the look, the mode and the non-default flags. */
export function makeSetup(app: string, table: FeatureTable, state: SetupState): SharedSetup {
const out: SharedSetup = { format: SETUP_FORMAT, version: SETUP_VERSION, app, flags: sparseFlags(table, state.flags) };
if (state.theme) out.theme = { preset: state.theme.preset, accent: state.theme.accent, ...(state.theme.icons ? { icons: state.theme.icons } : {}) };
if (table.modes.length) out.mode = modeById(table, state.mode) ? state.mode : null;
return out;
}
const toBase64Url = (text: string) => {
let binary = '';
for (const byte of new TextEncoder().encode(text)) binary += String.fromCharCode(byte);
return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
};
const fromBase64Url = (data: string) => {
const binary = atob(data.replace(/-/g, '+').replace(/_/g, '/'));
return new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(binary, char => char.charCodeAt(0)));
};
/** The file's text (pretty JSON). */
export const setupFile = (setup: SharedSetup): string => `${JSON.stringify(setup, null, 2)}\n`;
/** `waybetter://setup?app=x&d=<base64url of the JSON>`. */
export const setupLink = (setup: SharedSetup): string => `${SETUP_LINK}?app=${encodeURIComponent(setup.app)}&d=${toBase64Url(JSON.stringify(setup))}`;
export type SetupError = 'format' | 'version' | 'app' | 'size';
export type ReadSetup = { ok: true; setup: SharedSetup; dropped: string[] } | { ok: false; error: SetupError; app?: string };
/**
* Reads a pasted link or a file's text for `app`. Everything is checked against the app's own
* table: an unknown flag, a mode the app does not have or a malformed theme is dropped (named in
* `dropped`), never guessed; a setup for another app or of another format is refused whole.
*/
export function readSetup(input: string, app: string, table: FeatureTable): ReadSetup {
const text = input.trim();
if (new TextEncoder().encode(text).length > SETUP_MAX_BYTES) return { ok: false, error: 'size' };
let raw: unknown;
try {
if (text.startsWith(`${SETUP_LINK}?`) || text.startsWith(`${SETUP_LINK}/?`)) {
const data = new URLSearchParams(text.slice(text.indexOf('?') + 1)).get('d');
if (!data || !/^[A-Za-z0-9_-]+$/.test(data)) return { ok: false, error: 'format' };
raw = JSON.parse(fromBase64Url(data));
} else {
raw = JSON.parse(text);
}
} catch {
return { ok: false, error: 'format' };
}
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, error: 'format' };
const source = raw as Record<string, unknown>;
if (source.format !== SETUP_FORMAT) return { ok: false, error: 'format' };
if (source.version !== SETUP_VERSION) return { ok: false, error: 'version' };
if (source.app !== app) return { ok: false, error: 'app', ...(typeof source.app === 'string' && ID.test(source.app) ? { app: source.app } : {}) };
const dropped: string[] = [];
const known = normalizeFlags(table, {});
const flags: Flags = {};
const inFlags = source.flags && typeof source.flags === 'object' && !Array.isArray(source.flags) ? source.flags as Record<string, unknown> : {};
for (const [key, value] of Object.entries(inFlags)) {
if (key in known && typeof value === 'boolean') flags[key] = value;
else dropped.push(key);
}
const setup: SharedSetup = { format: SETUP_FORMAT, version: SETUP_VERSION, app, flags: sparseFlags(table, { ...known, ...flags }) };
const theme = source.theme as Record<string, unknown> | undefined;
if (theme !== undefined) {
const ok = theme && typeof theme === 'object' && typeof theme.preset === 'string' && ID.test(theme.preset)
&& (theme.accent === null || (typeof theme.accent === 'string' && COLOR.test(theme.accent)))
&& (theme.icons === undefined || (typeof theme.icons === 'string' && ID.test(theme.icons)));
if (ok) setup.theme = { preset: theme.preset as string, accent: theme.accent as string | null, ...(theme.icons ? { icons: theme.icons as string } : {}) };
else dropped.push('theme');
}
if (source.mode !== undefined) {
if (source.mode === null || (typeof source.mode === 'string' && modeById(table, source.mode))) setup.mode = source.mode as string | null;
else dropped.push('mode');
}
return { ok: true, setup, dropped };
}
export type SetupPlan = {
/** The theme to switch to (absent: unchanged, or not installed here: see `missingTheme`). */
theme?: { from: string; to: string };
accent?: { from: string | null; to: string | null };
icons?: { from: string | undefined; to: string | undefined };
/** A theme / icon pack the setup names that this app does not have: yours stays. */
missingTheme?: string;
missingIcons?: string;
mode?: { from: string | null; to: string | null };
/** Flags the setup turns on and off (table order). */
on: string[];
off: string[];
/** Nothing would change. */
same: boolean;
};
/**
* What applying `setup` to `now` changes. `themes` / `iconPacks`: the ids installed here (plus the
* two icon choices every app has: undefined = the theme's own, "site" = the site's own).
*/
export function setupPlan(table: FeatureTable, now: SetupState, setup: SharedSetup, themes: ReadonlySet<string>, iconPacks: ReadonlySet<string>): SetupPlan {
const plan: SetupPlan = { on: [], off: [], same: true };
const current = normalizeFlags(table, now.flags);
const next = normalizeFlags(table, setup.flags);
for (const key of Object.keys(current)) {
if (current[key] === next[key]) continue;
(next[key] ? plan.on : plan.off).push(key);
}
if (setup.theme && now.theme) {
if (!themes.has(setup.theme.preset)) plan.missingTheme = setup.theme.preset;
else {
if (setup.theme.preset !== now.theme.preset) plan.theme = { from: now.theme.preset, to: setup.theme.preset };
if ((setup.theme.accent ?? null) !== (now.theme.accent ?? null)) plan.accent = { from: now.theme.accent ?? null, to: setup.theme.accent ?? null };
}
const icons = setup.theme.icons;
if (icons !== undefined && icons !== 'site' && !iconPacks.has(icons)) plan.missingIcons = icons;
else if (icons !== now.theme.icons) plan.icons = { from: now.theme.icons, to: icons };
}
if (setup.mode !== undefined && setup.mode !== now.mode) plan.mode = { from: now.mode, to: setup.mode };
plan.same = !plan.on.length && !plan.off.length && !plan.theme && !plan.accent && !plan.icons && !plan.mode;
return plan;
}
/** The state after applying `plan`: only what the plan lists changes; everything else stays as it is. */
export function applySetup(table: FeatureTable, now: SetupState, plan: SetupPlan): SetupState {
const flags = normalizeFlags(table, now.flags);
for (const key of plan.on) flags[key] = true;
for (const key of plan.off) flags[key] = false;
let theme = now.theme;
if (now.theme && (plan.theme || plan.accent || plan.icons)) {
const icons = plan.icons ? plan.icons.to : now.theme.icons;
theme = { preset: plan.theme?.to ?? now.theme.preset, accent: plan.accent ? plan.accent.to : now.theme.accent, ...(icons ? { icons } : {}) };
}
return { ...(theme ? { theme } : {}), mode: plan.mode ? plan.mode.to : now.mode, flags };
}

View file

@ -0,0 +1,136 @@
// "Share my setup" (panel/setupModel.ts): what a shared setup can carry (the look, the mode and the
// non-default flags, nothing personal), that a link and a file read back the same, that anything
// unknown or malformed is dropped or refused rather than guessed, and that importing changes exactly
// what the plan lists.
import assert from 'node:assert/strict';
import test from 'node:test';
import type { FeatureTable } from '../../runtime/src/featureTable.ts';
import { tableDefaults } from '../../runtime/src/featureTable.ts';
import {
SETUP_FORMAT, SETUP_LINK, SETUP_MAX_BYTES, applySetup, makeSetup, readSetup, setupFile, setupLink, setupPlan, type SetupState,
} from '../src/panel/setupModel.ts';
const TABLE: FeatureTable = {
areas: [
{ id: 'navigation', name: 'Navigation+', description: 'd', owner: 'wb-navigation-plus.plugin.js', namespace: 'navigation-plus' },
{ id: 'reader', name: 'Reader+', description: 'd', owner: 'wb-reader-plus.plugin.js', namespace: 'reader-plus' },
],
features: [
{ id: 'fixScroll', area: null, group: 'fixes', default: true, backing: 'app' },
{ id: 'hideTrends', area: 'navigation', default: false, backing: 'module' },
{ id: 'navigation.focusMode', area: 'navigation', default: false, backing: 'module' },
{ id: 'hideAds', area: 'reader', default: true, backing: 'app' },
],
modes: [
{ id: 'basic', name: 'b', description: 'b', flags: { 'area.navigation': false, 'area.reader': false } },
{ id: 'advanced', name: 'a', description: 'a', recommended: true, flags: { 'navigation.focusMode': true } },
],
};
const DEFAULTS = tableDefaults(TABLE);
const MINE: SetupState = {
theme: { preset: 'nord', accent: '#88c0d0', icons: 'pixel' },
mode: 'advanced',
flags: { ...DEFAULTS, 'navigation.focusMode': true, hideTrends: true, hideAds: false },
};
test('a setup carries the look, the mode and the non-default flags, and nothing else', () => {
const setup = makeSetup('x', TABLE, MINE);
assert.deepEqual(setup, {
format: SETUP_FORMAT, version: 1, app: 'x',
flags: { hideTrends: true, 'navigation.focusMode': true, hideAds: false },
theme: { preset: 'nord', accent: '#88c0d0', icons: 'pixel' },
mode: 'advanced',
});
// Whatever else the state object happens to hold never reaches the file.
const leaky = { ...MINE, profiles: ['@someone'], notes: { a: 'b' }, drafts: ['text'] } as SetupState;
assert.deepEqual(Object.keys(makeSetup('x', TABLE, leaky)).sort(), ['app', 'flags', 'format', 'mode', 'theme', 'version']);
// A mode the table does not know is saved as none; an app without modes saves no mode at all.
assert.equal(makeSetup('x', TABLE, { ...MINE, mode: 'gone' }).mode, null);
assert.equal('mode' in makeSetup('x', { ...TABLE, modes: [] }, MINE), false);
});
test('a link and a file read back to the same setup', () => {
const setup = makeSetup('x', TABLE, MINE);
const link = setupLink(setup);
assert.ok(link.startsWith(`${SETUP_LINK}?app=x&d=`));
assert.match(link.slice(link.indexOf('d=') + 2), /^[A-Za-z0-9_-]+$/, 'URL-safe, no padding');
for (const input of [link, setupFile(setup), ` ${link}\n`]) {
const read = readSetup(input, 'x', TABLE);
assert.ok(read.ok, input);
assert.deepEqual(read.setup, setup);
assert.deepEqual(read.dropped, []);
}
// An empty setup (everything at its default) is still a valid link.
const empty = readSetup(setupLink({ format: SETUP_FORMAT, version: 1, app: 'x', flags: {} }), 'x', TABLE);
assert.ok(empty.ok);
assert.deepEqual(empty.setup.flags, {});
});
test('another app, another format, a newer version or an oversized paste is refused whole', () => {
const setup = makeSetup('kick', TABLE, MINE);
assert.deepEqual(readSetup(setupLink(setup), 'x', TABLE), { ok: false, error: 'app', app: 'kick' });
assert.deepEqual(readSetup('{"format":"waybetter-backup"}', 'x', TABLE), { ok: false, error: 'format' });
assert.deepEqual(readSetup(JSON.stringify({ ...makeSetup('x', TABLE, MINE), version: 2 }), 'x', TABLE), { ok: false, error: 'version' });
assert.deepEqual(readSetup('not json', 'x', TABLE), { ok: false, error: 'format' });
assert.deepEqual(readSetup(`${SETUP_LINK}?app=x&d=%%%`, 'x', TABLE), { ok: false, error: 'format' });
assert.deepEqual(readSetup(`${SETUP_LINK}?app=x&d=bm90IGpzb24`, 'x', TABLE), { ok: false, error: 'format' });
assert.deepEqual(readSetup('x'.repeat(SETUP_MAX_BYTES + 1), 'x', TABLE), { ok: false, error: 'size' });
assert.deepEqual(readSetup('[]', 'x', TABLE), { ok: false, error: 'format' });
});
test('unknown flags, a foreign mode and a malformed theme are dropped and named, never guessed', () => {
const raw = {
format: SETUP_FORMAT, version: 1, app: 'x',
flags: { hideTrends: true, 'p.someone.plugin': true, hideAds: 'yes', 'area.chat': false },
theme: { preset: '<script>', accent: 'red' },
mode: 'power',
notes: { '@someone': 'secret' },
};
const read = readSetup(JSON.stringify(raw), 'x', TABLE);
assert.ok(read.ok);
assert.deepEqual(read.setup, { format: SETUP_FORMAT, version: 1, app: 'x', flags: { hideTrends: true } });
assert.deepEqual(read.dropped.sort(), ['area.chat', 'hideAds', 'mode', 'p.someone.plugin', 'theme']);
assert.equal('notes' in read.setup, false, 'fields a setup does not have are not carried over');
});
test('the plan lists exactly what changes; applying it changes nothing else', () => {
const setup = makeSetup('x', TABLE, MINE);
const now: SetupState = { theme: { preset: 'x', accent: null }, mode: null, flags: DEFAULTS };
const themes = new Set(['x', 'nord']);
const packs = new Set(['pixel']);
const plan = setupPlan(TABLE, now, setup, themes, packs);
assert.deepEqual(plan, {
on: ['hideTrends', 'navigation.focusMode'], off: ['hideAds'], same: false,
theme: { from: 'x', to: 'nord' }, accent: { from: null, to: '#88c0d0' }, icons: { from: undefined, to: 'pixel' },
mode: { from: null, to: 'advanced' },
});
const after = applySetup(TABLE, now, plan);
assert.deepEqual(after, MINE);
// Applied twice: nothing more to do.
assert.equal(setupPlan(TABLE, after, setup, themes, packs).same, true);
});
test('a theme or icon pack that is not installed here is named and left alone', () => {
const setup = makeSetup('x', TABLE, { ...MINE, theme: { preset: 'my-own-theme', accent: '#112233', icons: 'someone-pack' } });
const now: SetupState = { theme: { preset: 'x', accent: null }, mode: 'advanced', flags: MINE.flags };
const plan = setupPlan(TABLE, now, setup, new Set(['x']), new Set());
assert.equal(plan.missingTheme, 'my-own-theme');
assert.equal(plan.missingIcons, 'someone-pack');
assert.equal(plan.theme, undefined);
assert.equal(plan.accent, undefined, 'an accent belongs to its theme');
assert.equal(plan.icons, undefined);
assert.equal(plan.same, true, 'nothing else differs, so nothing would change');
assert.deepEqual(applySetup(TABLE, now, plan), now);
// "site" (the site's own icons) is a choice every app has.
const site = setupPlan(TABLE, now, makeSetup('x', TABLE, { ...MINE, theme: { preset: 'x', accent: null, icons: 'site' } }), new Set(['x']), new Set());
assert.deepEqual(site.icons, { from: undefined, to: 'site' });
});
test('a setup without a theme or mode leaves the look and the mode alone', () => {
const setup = readSetup(JSON.stringify({ format: SETUP_FORMAT, version: 1, app: 'x', flags: { hideTrends: true } }), 'x', TABLE);
assert.ok(setup.ok);
const now: SetupState = { theme: { preset: 'nord', accent: '#88c0d0' }, mode: 'basic', flags: DEFAULTS };
const plan = setupPlan(TABLE, now, setup.setup, new Set(['nord']), new Set());
assert.deepEqual(plan, { on: ['hideTrends'], off: [], same: false });
assert.deepEqual(applySetup(TABLE, now, plan), { ...now, flags: { ...DEFAULTS, hideTrends: true } });
});