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:
parent
edc3655b2a
commit
2c7c143487
2 changed files with 309 additions and 0 deletions
173
packages/shell/src/panel/setupModel.ts
Normal file
173
packages/shell/src/panel/setupModel.ts
Normal 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 };
|
||||||
|
}
|
||||||
136
packages/shell/tests/setup.test.ts
Normal file
136
packages/shell/tests/setup.test.ts
Normal 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 } });
|
||||||
|
});
|
||||||
Loading…
Add table
Add a link
Reference in a new issue