@happyvertical/smrt-preferences 0.0.0-stage → 0.55.11

package/dist/index.js

@@ -0,0 +1,990 @@
+import { GlobalInterceptors, ObjectRegistry, RuntimeError, SmrtCollection, SmrtObject, crossPackageRef, field, resolveGetStringFilter, smrt } from "@happyvertical/smrt-core";
+import { assertOperationPermission, checkOperationPermission, getCurrentSessionPermissionContext, registerPermissionDefinitions } from "@happyvertical/smrt-users";
+import { checkOverviewOverride, diffOverview, loadOverview, optionsEqual, parseOverviewDocument, resolveOverview, sanitizeOverview } from "@happyvertical/smrt-svelte/overview/server";
+import { mergeShellSettingsDelta, sanitizeShellSettingsDelta } from "@happyvertical/smrt-svelte/workspace/server";
+import { TenantIsolationError, TenantScoped, getCurrentTenant, isSuperAdminBypass, tenantId, withTenant } from "@happyvertical/smrt-tenancy";
+//#region src/__smrt-register__.ts
+ObjectRegistry.registerPackageManifest(JSON.parse(`{"version":"1.0.0","timestamp":0,"packageName":"@happyvertical/smrt-preferences","packageVersion":"0.55.11","objects":{"@happyvertical/smrt-preferences:UiPreferenceRecordCollection":{"name":"uipreferencerecordcollection","className":"UiPreferenceRecordCollection","qualifiedName":"@happyvertical/smrt-preferences:UiPreferenceRecordCollection","collection":"uipreferencerecords","description":"Reads of UiPreferenceRecord. Not decorated: the model has no generated surface, so a decorated collection would only add a second manifest schema for the same table.","filePath":"/home/runner/work/smrt/smrt/packages/preferences/src/collections/UiPreferenceRecordCollection.ts","packageName":"@happyvertical/smrt-preferences","fields":{},"methods":{"findTier":{"name":"findTier","async":true,"parameters":[{"name":"tenantId","type":"string","optional":false},{"name":"kind","type":"string","optional":false},{"name":"surfaceId","type":"string","optional":false},{"name":"scope","type":"PreferenceScope","optional":false},{"name":"userId","type":"string","optional":true}],"returnType":"Promise<UiPreferenceRecord | null>","isStatic":false,"isPublic":true}},"decoratorConfig":{"tableName":"_smrt_ui_preferences","cli":false},"extends":"SmrtCollection","extendsTypeArg":"UiPreferenceRecord","exportName":"UiPreferenceRecordCollection","collectionExportName":"UiPreferenceRecordCollectionCollection","schema":{"tableName":"_smrt_ui_preferences","ddl":"CREATE TABLE IF NOT EXISTS \\"_smrt_ui_preferences\\" (\\n  \\"id\\" UUID PRIMARY KEY NOT NULL,\\n  \\"slug\\" TEXT NOT NULL,\\n  \\"context\\" TEXT NOT NULL DEFAULT '',\\n  \\"created_at\\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\\n  \\"updated_at\\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\\n  \\"tenant_id\\" UUID NOT NULL,\\n  \\"kind\\" TEXT NOT NULL DEFAULT '',\\n  \\"surface_id\\" TEXT NOT NULL DEFAULT '',\\n  \\"scope_type\\" TEXT NOT NULL DEFAULT 'tenant',\\n  \\"user_id\\" UUID,\\n  \\"scope_key\\" TEXT NOT NULL,\\n  \\"payload_json\\" TEXT NOT NULL,\\n  \\"format_version\\" INTEGER,\\n  \\"updated_by\\" UUID\\n);","columns":{"id":{"type":"UUID","primaryKey":true,"referenceKind":"id","notNull":true},"slug":{"type":"TEXT","notNull":true},"context":{"type":"TEXT","notNull":true,"default":""},"created_at":{"type":"TIMESTAMP","notNull":true,"default":"current_timestamp"},"updated_at":{"type":"TIMESTAMP","notNull":true,"default":"current_timestamp"},"tenant_id":{"type":"UUID","referenceKind":"tenantId","notNull":true,"unique":false},"kind":{"type":"TEXT","notNull":true,"unique":false,"default":""},"surface_id":{"type":"TEXT","notNull":true,"unique":false,"default":""},"scope_type":{"type":"TEXT","notNull":true,"unique":false,"default":"tenant"},"user_id":{"type":"UUID","referenceKind":"crossPackageRef","notNull":false,"unique":false},"scope_key":{"type":"TEXT","notNull":true,"unique":false},"payload_json":{"type":"TEXT","notNull":true,"unique":false},"format_version":{"type":"INTEGER","notNull":false,"unique":false},"updated_by":{"type":"UUID","referenceKind":"crossPackageRef","notNull":false,"unique":false}},"indexes":[{"name":"_smrt_ui_preferences_tenant_id_kind_idx","columns":["tenant_id","kind","surface_id","scope_type","scope_key"],"unique":true},{"name":"_smrt_ui_preferences_slug_context_idx","columns":["slug","context"]},{"name":"_smrt_ui_preferences_tenant_id_created_at_idx","columns":["tenant_id","created_at"]},{"name":"_smrt_ui_preferences_user_id_idx","columns":["user_id"]},{"name":"_smrt_ui_preferences_updated_by_idx","columns":["updated_by"]}],"version":"3f9df5fd"},"importPath":"@happyvertical/smrt-preferences"},"@happyvertical/smrt-preferences:UiPreferenceRecord":{"name":"uipreferencerecord","className":"UiPreferenceRecord","qualifiedName":"@happyvertical/smrt-preferences:UiPreferenceRecord","collection":"uipreferencerecords","description":"One stored user-interface preference (#3727): the canonical payload of a registered preference kind (overview, shell-layout, ...) for one surface at one tier of one tenant.","filePath":"/home/runner/work/smrt/smrt/packages/preferences/src/models/UiPreferenceRecord.ts","packageName":"@happyvertical/smrt-preferences","fields":{"tenantId":{"type":"text","required":true,"_meta":{"sqlType":"UUID","__tenancy":{"isTenantIdField":true,"autoFilter":true,"required":true,"autoPopulate":true,"nullable":false,"mode":"required","field":"tenantId","allowSuperAdminBypass":false}}},"kind":{"type":"text","required":true,"default":"","_meta":{"required":true}},"surfaceId":{"type":"text","required":true,"default":"","_meta":{"required":true}},"scopeType":{"type":"text","required":true,"default":"tenant","_meta":{"required":true}},"userId":{"type":"crossPackageRef","required":false,"related":"@happyvertical/smrt-users:User","_meta":{"nullable":true}},"scopeKey":{"type":"text","required":true,"_meta":{"required":true}},"payloadJson":{"type":"text","required":true,"_meta":{"required":true}},"formatVersion":{"type":"integer","required":false,"_meta":{}},"updatedBy":{"type":"crossPackageRef","required":false,"related":"@happyvertical/smrt-users:User","_meta":{"nullable":true}}},"methods":{"loadFromId":{"name":"loadFromId","async":true,"parameters":[],"returnType":"Promise<void>","isStatic":false,"isPublic":true},"loadFromSlug":{"name":"loadFromSlug","async":true,"parameters":[],"returnType":"Promise<void>","isStatic":false,"isPublic":true},"getPayload":{"name":"getPayload","async":false,"parameters":[],"returnType":"unknown","isStatic":false,"isPublic":true},"setPayload":{"name":"setPayload","async":false,"parameters":[{"name":"value","type":"unknown","optional":false}],"returnType":"void","isStatic":false,"isPublic":true},"save":{"name":"save","async":true,"parameters":[{"name":"options","type":"SaveOptions","optional":true}],"returnType":"Promise<this>","isStatic":false,"isPublic":true},"delete":{"name":"delete","async":true,"parameters":[{"name":"options","type":"DeleteOptions","optional":true}],"returnType":"Promise<void>","isStatic":false,"isPublic":true}},"decoratorConfig":{"tableName":"_smrt_ui_preferences","conflictColumns":["tenant_id","kind","surface_id","scope_type","scope_key"],"api":{"include":[]},"cli":false,"mcp":{"include":[]},"tenantScoped":{"mode":"required"}},"extends":"SmrtObject","exportName":"UiPreferenceRecord","collectionExportName":"UiPreferenceRecordCollection","validationRules":[{"field":"kind","rule":"required","fieldType":"text"},{"field":"surfaceId","rule":"required","fieldType":"text"},{"field":"scopeType","rule":"required","fieldType":"text"},{"field":"scopeKey","rule":"required","fieldType":"text"},{"field":"payloadJson","rule":"required","fieldType":"text"}],"schema":{"tableName":"_smrt_ui_preferences","ddl":"CREATE TABLE IF NOT EXISTS \\"_smrt_ui_preferences\\" (\\n  \\"id\\" UUID PRIMARY KEY NOT NULL,\\n  \\"slug\\" TEXT NOT NULL,\\n  \\"context\\" TEXT NOT NULL DEFAULT '',\\n  \\"created_at\\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\\n  \\"updated_at\\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\\n  \\"tenant_id\\" UUID NOT NULL,\\n  \\"kind\\" TEXT NOT NULL DEFAULT '',\\n  \\"surface_id\\" TEXT NOT NULL DEFAULT '',\\n  \\"scope_type\\" TEXT NOT NULL DEFAULT 'tenant',\\n  \\"user_id\\" UUID,\\n  \\"scope_key\\" TEXT NOT NULL,\\n  \\"payload_json\\" TEXT NOT NULL,\\n  \\"format_version\\" INTEGER,\\n  \\"updated_by\\" UUID\\n);","columns":{"id":{"type":"UUID","primaryKey":true,"referenceKind":"id","notNull":true},"slug":{"type":"TEXT","notNull":true},"context":{"type":"TEXT","notNull":true,"default":""},"created_at":{"type":"TIMESTAMP","notNull":true,"default":"current_timestamp"},"updated_at":{"type":"TIMESTAMP","notNull":true,"default":"current_timestamp"},"tenant_id":{"type":"UUID","referenceKind":"tenantId","notNull":true,"unique":false},"kind":{"type":"TEXT","notNull":true,"unique":false,"default":""},"surface_id":{"type":"TEXT","notNull":true,"unique":false,"default":""},"scope_type":{"type":"TEXT","notNull":true,"unique":false,"default":"tenant"},"user_id":{"type":"UUID","referenceKind":"crossPackageRef","notNull":false,"unique":false},"scope_key":{"type":"TEXT","notNull":true,"unique":false},"payload_json":{"type":"TEXT","notNull":true,"unique":false},"format_version":{"type":"INTEGER","notNull":false,"unique":false},"updated_by":{"type":"UUID","referenceKind":"crossPackageRef","notNull":false,"unique":false}},"indexes":[{"name":"_smrt_ui_preferences_tenant_id_kind_idx","columns":["tenant_id","kind","surface_id","scope_type","scope_key"],"unique":true},{"name":"_smrt_ui_preferences_slug_context_idx","columns":["slug","context"]},{"name":"_smrt_ui_preferences_tenant_id_created_at_idx","columns":["tenant_id","created_at"]},{"name":"_smrt_ui_preferences_user_id_idx","columns":["user_id"]},{"name":"_smrt_ui_preferences_updated_by_idx","columns":["updated_by"]}],"version":"3f9df5fd"},"importPath":"@happyvertical/smrt-preferences"}},"moduleType":"smrt","smrtDependencies":["@happyvertical/smrt-core","@happyvertical/smrt-tenancy","@happyvertical/smrt-users"],"browser":{"status":"server-only","issues":["#3617","#3624","#3626"],"via":["@happyvertical/smrt-profiles","@happyvertical/smrt-tenancy","@happyvertical/smrt-users"]},"stampsConstructors":true}`));
+//#endregion
+//#region src/permissions.ts
+var CUSTOMIZE_OVERVIEW_PERMISSION = "overviews.customize";
+var PERSONALIZE_OVERVIEW_PERMISSION = "overviews.personalize";
+var CUSTOMIZE_SHELL_PERMISSION = "shell.customize";
+var PERSONALIZE_SHELL_PERMISSION = "shell.personalize";
+var PREFERENCE_PERMISSION_DEFINITIONS = [
+	{
+		slug: CUSTOMIZE_OVERVIEW_PERMISSION,
+		category: "preferences",
+		name: "Customize Overviews",
+		description: "Change the default overview layouts everyone in the tenant sees"
+	},
+	{
+		slug: PERSONALIZE_OVERVIEW_PERMISSION,
+		category: "preferences",
+		name: "Personalize Overviews",
+		description: "Keep a personal overview layout on top of the tenant default"
+	},
+	{
+		slug: CUSTOMIZE_SHELL_PERMISSION,
+		category: "preferences",
+		name: "Customize Shell Layout",
+		description: "Change the default navigation and panel layout everyone in the tenant sees"
+	},
+	{
+		slug: PERSONALIZE_SHELL_PERMISSION,
+		category: "preferences",
+		name: "Personalize Shell Layout",
+		description: "Keep a personal navigation and panel layout on top of the tenant default"
+	}
+];
+var registered = false;
+function ensurePreferencePermissionsRegistered() {
+	if (registered) return;
+	registered = true;
+	registerPermissionDefinitions(PREFERENCE_PERMISSION_DEFINITIONS);
+}
+function splitPermissionSlug(slug) {
+	const dot = slug.lastIndexOf(".");
+	if (dot <= 0 || dot === slug.length - 1) throw new Error(`Preference permission "${slug}" is not collection.action`);
+	return {
+		collection: slug.slice(0, dot),
+		action: slug.slice(dot + 1)
+	};
+}
+//#endregion
+//#region src/kinds.ts
+var PREFERENCE_SCOPES = ["tenant", "user"];
+var PREFERENCE_KIND_PATTERN = /^[a-z][a-z0-9-]{0,47}$/;
+var PREFERENCE_SURFACE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,95}$/;
+var UnknownPreferenceKindError = class extends Error {
+	code = "unknown_preference_kind";
+	status = 400;
+	constructor(kind) {
+		super(`Preference kind "${kind}" is not registered`);
+		this.name = "UnknownPreferenceKindError";
+	}
+};
+var kinds = /* @__PURE__ */ new Map();
+function registerPreferenceKind(definition, options = {}) {
+	if (!PREFERENCE_KIND_PATTERN.test(definition.kind)) throw new Error(`Invalid preference kind "${definition.kind}"`);
+	if (!Number.isSafeInteger(definition.formatVersion) || definition.formatVersion < 1) throw new Error(`Preference kind "${definition.kind}" needs a positive formatVersion`);
+	splitPermissionSlug(definition.permissions.tenant);
+	splitPermissionSlug(definition.permissions.user);
+	if (typeof definition.validate !== "function") throw new Error(`Preference kind "${definition.kind}" needs validate()`);
+	if (kinds.has(definition.kind) && !options.replace) throw new Error(`Preference kind "${definition.kind}" is already registered`);
+	const frozen = Object.freeze({
+		...definition,
+		permissions: Object.freeze({ ...definition.permissions })
+	});
+	kinds.set(definition.kind, frozen);
+	return () => {
+		if (kinds.get(definition.kind) === frozen) kinds.delete(definition.kind);
+	};
+}
+function getPreferenceKind(kind) {
+	return kinds.get(kind);
+}
+function requirePreferenceKind(kind) {
+	const definition = kinds.get(kind);
+	if (!definition) throw new UnknownPreferenceKindError(kind);
+	return definition;
+}
+function listPreferenceKinds() {
+	return [...kinds.keys()];
+}
+//#endregion
+//#region src/kinds/overview.ts
+var OVERVIEW_PREFERENCE_KIND = "overview";
+function withTenantDefaults(definition, document) {
+	return {
+		...definition,
+		defaults: document.widgets
+	};
+}
+function toPreferenceIssue$1(issue) {
+	return {
+		path: issue.widgetId,
+		code: issue.code,
+		message: issue.message,
+		detail: issue
+	};
+}
+function toOverviewIssue(issue) {
+	if (issue.detail && typeof issue.detail === "object") return issue.detail;
+	return {
+		widgetId: null,
+		type: null,
+		code: issue.code === "future_version" ? "future_version" : "malformed",
+		message: issue.message
+	};
+}
+function readOptions(options) {
+	if (!options || typeof options !== "object") return null;
+	const { definition, registry } = options;
+	if (!definition || !registry) return null;
+	return {
+		definition,
+		registry
+	};
+}
+function overviewTierDefinition({ definition, registry }, scope, tenantOverride) {
+	if (scope === "tenant") return definition;
+	return withTenantDefaults(definition, resolveOverview(definition, tenantOverride ?? null, registry).document);
+}
+var overviewPreferenceKind = {
+	kind: OVERVIEW_PREFERENCE_KIND,
+	formatVersion: 1,
+	permissions: {
+		tenant: CUSTOMIZE_OVERVIEW_PERMISSION,
+		user: PERSONALIZE_OVERVIEW_PERMISSION
+	},
+	validate(payload, ctx) {
+		const options = readOptions(ctx.options);
+		if (!options || options.definition.id !== ctx.surfaceId) return {
+			ok: false,
+			canonical: null,
+			issues: [{
+				path: null,
+				code: "missing_context",
+				message: "the overview kind needs { definition, registry } for this surface"
+			}]
+		};
+		const definition = overviewTierDefinition(options, ctx.scope, ctx.tenant);
+		if (ctx.phase === "save") {
+			const checked = checkOverviewOverride(definition, payload, options.registry);
+			return checked.ok ? {
+				ok: true,
+				canonical: checked.override,
+				issues: []
+			} : {
+				ok: false,
+				canonical: null,
+				issues: checked.issues.map(toPreferenceIssue$1)
+			};
+		}
+		const resolved = resolveOverview(definition, payload, options.registry);
+		return {
+			ok: resolved.overrideIssues.length === 0,
+			canonical: diffOverview(resolved.base, resolved.document),
+			issues: resolved.overrideIssues.map(toPreferenceIssue$1)
+		};
+	}
+};
+//#endregion
+//#region src/kinds/shell-layout.ts
+var SHELL_LAYOUT_PREFERENCE_KIND = "shell-layout";
+function toPreferenceIssue(issue) {
+	return {
+		path: issue.path || null,
+		code: "invalid_setting",
+		message: issue.message,
+		detail: issue
+	};
+}
+var shellLayoutPreferenceKind = {
+	kind: SHELL_LAYOUT_PREFERENCE_KIND,
+	formatVersion: 1,
+	permissions: {
+		tenant: CUSTOMIZE_SHELL_PERMISSION,
+		user: PERSONALIZE_SHELL_PERMISSION
+	},
+	validate(payload) {
+		const { delta, issues } = sanitizeShellSettingsDelta(payload);
+		return {
+			ok: issues.length === 0,
+			canonical: Object.keys(delta).length > 0 ? delta : null,
+			issues: issues.map(toPreferenceIssue)
+		};
+	}
+};
+function compact(delta) {
+	return Object.fromEntries(Object.entries(delta).filter(([, value]) => value !== void 0));
+}
+function createShellSettingsPreferences(store) {
+	return {
+		async read(surfaceId) {
+			const state = await store.load(SHELL_LAYOUT_PREFERENCE_KIND, surfaceId);
+			const tenant = state.tenant.payload ?? null;
+			const user = state.user?.payload ?? null;
+			return {
+				delta: compact(mergeShellSettingsDelta(tenant ?? {}, user ?? {})),
+				tenant,
+				user,
+				revisions: {
+					tenant: state.tenant.revision,
+					user: state.user?.revision ?? null
+				},
+				issues: state.issues,
+				canCustomize: state.canCustomize
+			};
+		},
+		async write(surfaceId, delta, options = {}) {
+			const scope = options.scope ?? "user";
+			let revision = options.revision;
+			if (revision === void 0) {
+				const state = await store.load(SHELL_LAYOUT_PREFERENCE_KIND, surfaceId);
+				revision = scope === "tenant" ? state.tenant.revision : state.user?.revision ?? null;
+			}
+			return store.save(SHELL_LAYOUT_PREFERENCE_KIND, surfaceId, {
+				scope,
+				payload: delta,
+				revision
+			});
+		},
+		reset(surfaceId, options = {}) {
+			return store.reset(SHELL_LAYOUT_PREFERENCE_KIND, surfaceId, {
+				scope: options.scope ?? "user",
+				revision: options.revision
+			});
+		}
+	};
+}
+//#endregion
+//#region src/kinds/builtin.ts
+function ensureBuiltinPreferenceKinds() {
+	for (const kind of [overviewPreferenceKind, shellLayoutPreferenceKind]) if (!getPreferenceKind(kind.kind)) registerPreferenceKind(kind);
+}
+ensureBuiltinPreferenceKinds();
+//#endregion
+//#region src/context.ts
+function getPreferencePrincipal() {
+	const tenant = getCurrentTenant();
+	if (tenant?.tenantId) return {
+		tenantId: tenant.tenantId,
+		userId: tenant.userId,
+		permissions: tenant.permissions,
+		superAdminBypass: isSuperAdminBypass(),
+		fromTenancy: true
+	};
+	const session = getCurrentSessionPermissionContext();
+	if (!session?.tenantId) return void 0;
+	return {
+		tenantId: session.tenantId,
+		userId: session.userId ?? void 0,
+		permissions: session.permissionSet,
+		superAdminBypass: session.superAdminBypass,
+		fromTenancy: false
+	};
+}
+var PreferenceAccessError = class extends TenantIsolationError {
+	status = 403;
+	publicMessage;
+	constructor(message) {
+		super(message);
+		this.name = "PreferenceAccessError";
+		this.publicMessage = message;
+	}
+};
+function requirePreferencePrincipal() {
+	const principal = getPreferencePrincipal();
+	if (!principal) throw new PreferenceAccessError("User-interface preferences need an authenticated tenant context");
+	return principal;
+}
+async function withPrincipal(principal, fn) {
+	if (principal.fromTenancy) return fn();
+	return withTenant({
+		tenantId: principal.tenantId,
+		userId: principal.userId,
+		permissions: new Set(principal.permissions)
+	}, fn);
+}
+//#endregion
+//#region src/read-guard.ts
+var GUARD_NAME = "smrt-preferences:owner-reads";
+var CLASS_NAME = "UiPreferenceRecord";
+var QUALIFIED_NAME = "@happyvertical/smrt-preferences:UiPreferenceRecord";
+function field$1(row, camel, snake) {
+	if (!row || typeof row !== "object") return void 0;
+	const record = row;
+	return record[camel] !== void 0 ? record[camel] : record[snake];
+}
+function isPreferenceRowVisible(row) {
+	const scope = field$1(row, "scopeType", "scope_type");
+	if (scope === "tenant") return true;
+	if (scope !== "user") return false;
+	const owner = field$1(row, "userId", "user_id");
+	const userId = getPreferencePrincipal()?.userId;
+	return Boolean(userId) && typeof owner === "string" && owner === userId;
+}
+function isPreferenceClass(className, qualifiedClassName) {
+	return qualifiedClassName === QUALIFIED_NAME || className === CLASS_NAME;
+}
+var TENANT_KEY = "__tenant__";
+var NO_ROW_KEY = "";
+var SCOPE_KEY_IN = ["scopeKey in", "scope_key in"];
+function visibleScopeKeys() {
+	const userId = getPreferencePrincipal()?.userId;
+	return userId ? [TENANT_KEY, userId] : [TENANT_KEY];
+}
+function withOwnerPredicate(where) {
+	const visible = visibleScopeKeys();
+	const next = { ...where ?? {} };
+	let keys = visible;
+	for (const key of SCOPE_KEY_IN) {
+		if (!(key in next)) continue;
+		const requested = next[key];
+		delete next[key];
+		const list = Array.isArray(requested) ? requested : [requested];
+		keys = keys.filter((value) => list.includes(value));
+	}
+	next["scopeKey in"] = keys.length > 0 ? keys : [NO_ROW_KEY];
+	return next;
+}
+function filterRows(className, rows, qualifiedClassName) {
+	if (!isPreferenceClass(className, qualifiedClassName)) return void 0;
+	return rows.filter(isPreferenceRowVisible);
+}
+function ensurePreferenceReadGuard() {
+	if (GlobalInterceptors.getAll().some((entry) => entry.name === GUARD_NAME)) return;
+	GlobalInterceptors.register({
+		name: GUARD_NAME,
+		priority: 90,
+		beforeList(className, options, context) {
+			if (!isPreferenceClass(className, context.qualifiedClassName)) return;
+			const where = options.where;
+			if (Array.isArray(where)) return {
+				...options,
+				where: where.map((group) => [...group, withOwnerPredicate({})])
+			};
+			return {
+				...options,
+				where: withOwnerPredicate(where)
+			};
+		},
+		beforeGet(className, filter, context) {
+			if (!isPreferenceClass(className, context.qualifiedClassName)) return;
+			return withOwnerPredicate(typeof filter === "string" ? resolveGetStringFilter(filter) : filter);
+		},
+		beforeQuery(className, _options, context) {
+			if (!isPreferenceClass(className, context.qualifiedClassName)) return;
+			throw new PreferenceAccessError("Raw queries over user-interface preferences are not allowed");
+		},
+		afterList(className, results, context) {
+			return filterRows(className, results, context.qualifiedClassName);
+		},
+		afterQuery(className, results, context) {
+			return filterRows(className, results, context.qualifiedClassName);
+		},
+		afterGet(className, instance, context) {
+			if (!instance || !isPreferenceClass(className, context.qualifiedClassName)) return;
+			return isPreferenceRowVisible(instance) ? instance : null;
+		}
+	});
+}
+//#endregion
+//#region src/write-capability.ts
+var STORE_WRITE = /* @__PURE__ */ Symbol("smrt-preferences.storeWrite");
+var TOKEN = Object.freeze({ capability: "smrt-preferences.storeWrite" });
+var writes = /* @__PURE__ */ new WeakMap();
+var deletes = /* @__PURE__ */ new WeakSet();
+function storeWriteOption() {
+	return { [STORE_WRITE]: TOKEN };
+}
+function adoptStoreWrite(instance, options) {
+	if (options && typeof options === "object" && options[STORE_WRITE] === TOKEN && typeof options.payloadJson === "string") writes.set(instance, options.payloadJson);
+}
+function grantStoreWrite(instance) {
+	writes.set(instance, instance.payloadJson);
+}
+function grantStoreDelete(instance) {
+	deletes.add(instance);
+}
+function hasStoreWrite(instance, payloadJson) {
+	return writes.get(instance) === payloadJson;
+}
+function spendStoreWrite(instance) {
+	writes.delete(instance);
+}
+function takeStoreDelete(instance) {
+	return deletes.delete(instance);
+}
+//#endregion
+//#region src/models/UiPreferenceRecord.ts
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, {
+	enumerable: true,
+	configurable: true,
+	writable: true,
+	value
+}) : obj[key] = value;
+var __decorateClass = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+	if (kind && result) __defProp(target, key, result);
+	return result;
+};
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+ensurePreferencePermissionsRegistered();
+ensurePreferenceReadGuard();
+var TENANT_SCOPE_KEY = "__tenant__";
+var UiPreferenceRecord = class extends SmrtObject {
+	tenantId = "";
+	kind = "";
+	surfaceId = "";
+	scopeType = "tenant";
+	userId = null;
+	scopeKey = "";
+	payloadJson = "";
+	formatVersion = 1;
+	updatedBy = null;
+	constructor(options = {}) {
+		super(options);
+		adoptStoreWrite(this, options);
+	}
+	/**
+	* Single-row hydration (`new UiPreferenceRecord({ id }).initialize()`)
+	* reads the table directly, outside the collection interceptors, so the
+	* owner check runs here: another user's row is wiped and refused.
+	*/
+	async loadFromId() {
+		await super.loadFromId();
+		this.assertReadable();
+	}
+	async loadFromSlug() {
+		await super.loadFromSlug();
+		this.assertReadable();
+	}
+	assertReadable() {
+		if (!this.kind || isPreferenceRowVisible(this)) return;
+		this.payloadJson = "";
+		throw new PreferenceAccessError("A personal preference can only be read by its owner");
+	}
+	/** The stored payload, parsed. `undefined` when the text is not JSON. */
+	getPayload() {
+		try {
+			return JSON.parse(this.payloadJson);
+		} catch {
+			return;
+		}
+	}
+	/** Store a payload; the caller passes the kind's canonical value. */
+	setPayload(value) {
+		this.payloadJson = JSON.stringify(value);
+	}
+	/** The optimistic-concurrency token a client echoes back on save. */
+	get revision() {
+		const at = this.updated_at;
+		if (!at) return null;
+		const date = at instanceof Date ? at : new Date(at);
+		return Number.isNaN(date.getTime()) ? null : date.toISOString();
+	}
+	async save(options = {}) {
+		const principal = requirePreferencePrincipal();
+		if (!this.tenantId) this.tenantId = principal.tenantId;
+		this.syncScopeKey();
+		await this.assertPersistedIdentityUnchanged();
+		this.assertStoreWrite();
+		this.validateShape();
+		await this.authorize();
+		this.updatedBy = principal.userId ?? null;
+		try {
+			return await super.save(options);
+		} finally {
+			spendStoreWrite(this);
+		}
+	}
+	/**
+	* Runs for ordinary saves and bulk creates alike, so a collection-level
+	* bulk insert is refused too (`save()` checks first so callers see it).
+	*/
+	async validateBeforeSave() {
+		await super.validateBeforeSave();
+		this.assertStoreWrite();
+	}
+	async delete(options = {}) {
+		if (!takeStoreDelete(this)) throw new PreferenceAccessError("Preferences are reset only through the preference store");
+		this.syncScopeKey();
+		await this.assertPersistedIdentityUnchanged();
+		await this.authorize();
+		return super.delete(options);
+	}
+	/**
+	* Only the store, after the kind's validator accepted exactly this
+	* payload, may write a row (see `write-capability.ts`).
+	*/
+	assertStoreWrite() {
+		if (!hasStoreWrite(this, this.payloadJson)) throw new PreferenceAccessError("Preferences are written only through the preference store, which validates them");
+	}
+	syncScopeKey() {
+		if (this.scopeType === "tenant" && this.userId === null) this.scopeKey = TENANT_SCOPE_KEY;
+		else if (this.scopeType === "user" && this.userId) this.scopeKey = this.userId;
+	}
+	validateShape() {
+		if (!PREFERENCE_KIND_PATTERN.test(this.kind)) throw new Error("UiPreferenceRecord.kind is not a valid kind id");
+		if (!PREFERENCE_SURFACE_PATTERN.test(this.surfaceId)) throw new Error("UiPreferenceRecord.surfaceId is not a valid id");
+		if (!PREFERENCE_SCOPES.includes(this.scopeType)) throw new Error("UiPreferenceRecord.scopeType must be tenant or user");
+		if (this.scopeType === "tenant" && this.userId !== null) throw new Error("A tenant-default preference row has no userId");
+		if (this.scopeType === "user" && !this.userId) throw new Error("A user preference row needs its userId");
+		if (!Number.isSafeInteger(this.formatVersion) || this.formatVersion < 1) throw new Error("UiPreferenceRecord.formatVersion must be positive");
+		if (this.getPayload() === void 0) throw new Error("UiPreferenceRecord.payloadJson must be JSON");
+	}
+	/**
+	* Fail-closed tier guard. The tenant must be the principal's (the
+	* interceptor checks this too; a super-admin bypass does not filter reads,
+	* so it is re-checked here), a user row must belong to the principal (a
+	* principal with no user id may not touch the user tier), the kind must be
+	* registered, and its permission for the tier must be held.
+	*/
+	async authorize() {
+		const principal = requirePreferencePrincipal();
+		const kind = requirePreferenceKind(this.kind);
+		if (this.tenantId !== principal.tenantId) throw new PreferenceAccessError("This preference belongs to another tenant");
+		if (this.scopeType === "user") {
+			if (!principal.userId || this.userId !== principal.userId) throw new PreferenceAccessError("A personal preference can only be changed by its owner");
+		}
+		await assertOperationPermission({
+			...splitPermissionSlug(this.scopeType === "user" ? kind.permissions.user : kind.permissions.tenant),
+			db: this.options.db ?? this.options.persistence,
+			tenantId: principal.tenantId,
+			userId: principal.userId ?? null,
+			permissionSet: principal.permissions
+		});
+	}
+	/**
+	* A persisted row keeps its identity: the stored tenant, kind, surface and
+	* tier must be the ones in memory, so {@link authorize} always judges the
+	* row as stored. Matched by predicate rather than by reading the columns
+	* back, because DuckDB returns raw UUID columns as lossy HUGEINTs.
+	*/
+	async assertPersistedIdentityUnchanged() {
+		if (!this.id) return;
+		if (!await this.db.get(this.tableName, { id: this.id })) return;
+		if (!await this.db.get(this.tableName, {
+			id: this.id,
+			tenant_id: this.tenantId,
+			kind: this.kind,
+			surface_id: this.surfaceId,
+			scope_type: this.scopeType,
+			scope_key: this.scopeKey
+		})) throw new PreferenceAccessError("A preference row cannot change its tenant, kind, surface or owner");
+	}
+};
+__publicField(UiPreferenceRecord, "__smrtPackage__", "@happyvertical/smrt-preferences");
+__decorateClass([tenantId()], UiPreferenceRecord.prototype, "tenantId", 2);
+__decorateClass([field({ required: true })], UiPreferenceRecord.prototype, "kind", 2);
+__decorateClass([field({ required: true })], UiPreferenceRecord.prototype, "surfaceId", 2);
+__decorateClass([field({ required: true })], UiPreferenceRecord.prototype, "scopeType", 2);
+__decorateClass([crossPackageRef("@happyvertical/smrt-users:User", { nullable: true })], UiPreferenceRecord.prototype, "userId", 2);
+__decorateClass([field({
+	type: "text",
+	required: true
+})], UiPreferenceRecord.prototype, "scopeKey", 2);
+__decorateClass([field({
+	type: "text",
+	required: true
+})], UiPreferenceRecord.prototype, "payloadJson", 2);
+__decorateClass([field({ type: "integer" })], UiPreferenceRecord.prototype, "formatVersion", 2);
+__decorateClass([crossPackageRef("@happyvertical/smrt-users:User", { nullable: true })], UiPreferenceRecord.prototype, "updatedBy", 2);
+UiPreferenceRecord = __decorateClass([TenantScoped({ mode: "required" }), smrt({
+	tableName: "_smrt_ui_preferences",
+	conflictColumns: [
+		"tenant_id",
+		"kind",
+		"surface_id",
+		"scope_type",
+		"scope_key"
+	],
+	api: { include: [] },
+	cli: false,
+	mcp: { include: [] }
+})], UiPreferenceRecord);
+//#endregion
+//#region src/collections/UiPreferenceRecordCollection.ts
+var UiPreferenceRecordCollection = class extends SmrtCollection {
+	static _itemClass = UiPreferenceRecord;
+	/**
+	* The row of one tier, or `null`. The tenant predicate is explicit (not
+	* only the interceptor's) because a super-admin bypass context does not
+	* filter reads.
+	*/
+	async findTier(tenantId, kind, surfaceId, scope, userId) {
+		const scopeKey = scope === "tenant" ? TENANT_SCOPE_KEY : userId;
+		if (!scopeKey) return null;
+		return (await this.list({
+			where: {
+				tenantId,
+				kind,
+				surfaceId,
+				scopeType: scope,
+				scopeKey
+			},
+			limit: 1
+		}))[0] ?? null;
+	}
+};
+//#endregion
+//#region src/store.ts
+function isRevisionConflict(error) {
+	return error instanceof RuntimeError && error.code === "RUNTIME_REVISION_CONFLICT";
+}
+function assertSurfaceId(surfaceId) {
+	if (!PREFERENCE_SURFACE_PATTERN.test(surfaceId)) throw new Error(`Invalid preference surface id "${surfaceId}"`);
+}
+async function holds(principal, slug, db) {
+	return (await checkOperationPermission({
+		...splitPermissionSlug(slug),
+		db,
+		tenantId: principal.tenantId,
+		userId: principal.userId ?? null,
+		permissionSet: principal.permissions,
+		onDeny: "return"
+	})).allowed;
+}
+async function canWrite(principal, kind, scope, db) {
+	if (scope === "user") return Boolean(principal.userId) && await holds(principal, kind.permissions.user, db);
+	return holds(principal, kind.permissions.tenant, db);
+}
+function readTier(kind, surfaceId, scope, row, options, tenant) {
+	if (!row) return {
+		payload: null,
+		revision: null,
+		issues: []
+	};
+	const revision = row.revision;
+	const payload = row.getPayload();
+	if (payload === void 0) return {
+		payload: null,
+		revision,
+		issues: [{
+			path: null,
+			code: "malformed",
+			message: "stored payload is not JSON"
+		}]
+	};
+	if (row.formatVersion > kind.formatVersion) return {
+		payload: null,
+		revision,
+		issues: [{
+			path: null,
+			code: "future_version",
+			message: "stored payload was written by a newer format version"
+		}]
+	};
+	let checked;
+	try {
+		checked = kind.validate(payload, {
+			kind: kind.kind,
+			surfaceId,
+			scope,
+			phase: "load",
+			formatVersion: row.formatVersion,
+			...scope === "user" ? { tenant: tenant ?? null } : {},
+			options
+		});
+	} catch {
+		return {
+			payload: null,
+			revision,
+			issues: [{
+				path: null,
+				code: "validator_error",
+				message: "the preference kind failed to validate the stored payload"
+			}]
+		};
+	}
+	return {
+		payload: checked.canonical,
+		revision,
+		issues: checked.issues
+	};
+}
+function createPreferenceStore(options) {
+	const { db } = options;
+	const collection = () => {
+		ensurePreferenceReadGuard();
+		return UiPreferenceRecordCollection.create({ db });
+	};
+	async function tenantTier(records, principal, kind, surfaceId, kindOptions) {
+		return readTier(kind, surfaceId, "tenant", await records.findTier(principal.tenantId, kind.kind, surfaceId, "tenant"), kindOptions);
+	}
+	return {
+		async load(kindId, surfaceId, input = {}) {
+			const kind = requirePreferenceKind(kindId);
+			assertSurfaceId(surfaceId);
+			const principal = requirePreferencePrincipal();
+			return withPrincipal(principal, async () => {
+				const records = await collection();
+				const tenant = await tenantTier(records, principal, kind, surfaceId, input.options);
+				const userRow = principal.userId ? await records.findTier(principal.tenantId, kind.kind, surfaceId, "user", principal.userId) : null;
+				const user = principal.userId ? readTier(kind, surfaceId, "user", userRow, input.options, tenant.payload) : null;
+				const [tenantWrite, userWrite] = await Promise.all([canWrite(principal, kind, "tenant", db), canWrite(principal, kind, "user", db)]);
+				return {
+					kind: kind.kind,
+					surfaceId,
+					tenant,
+					user,
+					issues: [...tenant.issues, ...user?.issues ?? []],
+					canCustomize: {
+						tenant: tenantWrite,
+						user: userWrite
+					}
+				};
+			});
+		},
+		async save(kindId, surfaceId, input) {
+			const kind = requirePreferenceKind(kindId);
+			assertSurfaceId(surfaceId);
+			const principal = requirePreferencePrincipal();
+			return withPrincipal(principal, async () => {
+				if (!await canWrite(principal, kind, input.scope, db)) return {
+					ok: false,
+					reason: "not_allowed"
+				};
+				const records = await collection();
+				const tenant = input.scope === "user" ? (await tenantTier(records, principal, kind, surfaceId, input.options)).payload : void 0;
+				const checked = kind.validate(input.payload, {
+					kind: kind.kind,
+					surfaceId,
+					scope: input.scope,
+					phase: "save",
+					formatVersion: kind.formatVersion,
+					...input.scope === "user" ? { tenant: tenant ?? null } : {},
+					options: input.options
+				});
+				if (!checked.ok) return {
+					ok: false,
+					reason: "invalid",
+					issues: checked.issues
+				};
+				const canonical = checked.canonical ?? null;
+				const userId = input.scope === "user" ? principal.userId : void 0;
+				const existing = await records.findTier(principal.tenantId, kind.kind, surfaceId, input.scope, userId);
+				const revision = input.revision ?? null;
+				if (canonical === null) {
+					if (!existing) return revision === null ? {
+						ok: true,
+						payload: null,
+						revision: null
+					} : {
+						ok: false,
+						reason: "conflict"
+					};
+					if (revision === null) return {
+						ok: false,
+						reason: "conflict"
+					};
+					try {
+						grantStoreDelete(existing);
+						await existing.delete({ expectedUpdatedAt: revision });
+					} catch (error) {
+						if (isRevisionConflict(error)) return {
+							ok: false,
+							reason: "conflict"
+						};
+						throw error;
+					}
+					return {
+						ok: true,
+						payload: null,
+						revision: null
+					};
+				}
+				if (existing) {
+					if (revision === null) return {
+						ok: false,
+						reason: "conflict"
+					};
+					existing.setPayload(canonical);
+					existing.formatVersion = kind.formatVersion;
+					grantStoreWrite(existing);
+					try {
+						await existing.save({ expectedUpdatedAt: revision });
+					} catch (error) {
+						if (isRevisionConflict(error)) return {
+							ok: false,
+							reason: "conflict"
+						};
+						throw error;
+					}
+					return {
+						ok: true,
+						payload: canonical,
+						revision: existing.revision
+					};
+				}
+				if (revision !== null) return {
+					ok: false,
+					reason: "conflict"
+				};
+				try {
+					return {
+						ok: true,
+						payload: canonical,
+						revision: (await records.create({
+							tenantId: principal.tenantId,
+							kind: kind.kind,
+							surfaceId,
+							scopeType: input.scope,
+							userId: userId ?? null,
+							payloadJson: JSON.stringify(canonical),
+							formatVersion: kind.formatVersion,
+							_insertOnly: true,
+							...storeWriteOption()
+						})).revision
+					};
+				} catch (error) {
+					if (await records.findTier(principal.tenantId, kind.kind, surfaceId, input.scope, userId)) return {
+						ok: false,
+						reason: "conflict"
+					};
+					throw error;
+				}
+			});
+		},
+		async reset(kindId, surfaceId, input) {
+			const kind = requirePreferenceKind(kindId);
+			assertSurfaceId(surfaceId);
+			const principal = requirePreferencePrincipal();
+			return withPrincipal(principal, async () => {
+				if (!await canWrite(principal, kind, input.scope, db)) return {
+					ok: false,
+					reason: "not_allowed"
+				};
+				const existing = await (await collection()).findTier(principal.tenantId, kind.kind, surfaceId, input.scope, input.scope === "user" ? principal.userId : void 0);
+				if (!existing) return { ok: true };
+				if (input.revision === null) return {
+					ok: false,
+					reason: "conflict"
+				};
+				try {
+					grantStoreDelete(existing);
+					await existing.delete(typeof input.revision === "string" ? { expectedUpdatedAt: input.revision } : {});
+				} catch (error) {
+					if (isRevisionConflict(error)) return {
+						ok: false,
+						reason: "conflict"
+					};
+					throw error;
+				}
+				return { ok: true };
+			});
+		}
+	};
+}
+//#endregion
+//#region src/overview.ts
+function sameWidget(a, b) {
+	return a.id === b.id && a.type === b.type && (a.version ?? 1) === (b.version ?? 1) && optionsEqual(a.options, b.options);
+}
+function createOverviewStore(options) {
+	const preferences = options.preferences ?? createPreferenceStore({ db: options.db });
+	const kindOptions = (definition, registry) => ({
+		definition,
+		registry
+	});
+	const store = {
+		async load(definition, registry) {
+			const state = await preferences.load(OVERVIEW_PREFERENCE_KIND, definition.id, { options: kindOptions(definition, registry) });
+			const tenantOverride = state.tenant.payload;
+			const tenantResolved = resolveOverview(definition, tenantOverride, registry);
+			const tenant = {
+				base: tenantResolved.base,
+				document: tenantResolved.document,
+				override: tenantOverride,
+				revision: state.tenant.revision,
+				issues: state.tenant.issues.map(toOverviewIssue)
+			};
+			let user = null;
+			if (state.user) {
+				const userOverride = state.user.payload;
+				const userResolved = resolveOverview(withTenantDefaults(definition, tenant.document), userOverride, registry);
+				user = {
+					base: userResolved.base,
+					document: userResolved.document,
+					override: userOverride,
+					revision: state.user.revision,
+					issues: state.user.issues.map(toOverviewIssue)
+				};
+			}
+			return {
+				overviewId: definition.id,
+				tenant,
+				user,
+				document: user?.document ?? tenant.document,
+				issues: [...tenant.issues, ...user?.issues ?? []],
+				canCustomize: state.canCustomize
+			};
+		},
+		async save(definition, registry, input) {
+			const result = await preferences.save(OVERVIEW_PREFERENCE_KIND, definition.id, {
+				scope: input.scope,
+				payload: input.override,
+				revision: input.revision,
+				options: kindOptions(definition, registry)
+			});
+			if (result.ok) return {
+				ok: true,
+				override: result.payload,
+				revision: result.revision
+			};
+			if (result.reason === "invalid") return {
+				ok: false,
+				reason: "invalid",
+				issues: result.issues.map(toOverviewIssue)
+			};
+			return result;
+		},
+		async reset(definition, input) {
+			const result = await preferences.reset(OVERVIEW_PREFERENCE_KIND, definition.id, input);
+			if (!result.ok && result.reason === "invalid") return {
+				ok: false,
+				reason: "invalid",
+				issues: result.issues.map(toOverviewIssue)
+			};
+			return result;
+		},
+		async loadPage(definition, registry, ctx, pageOptions = {}) {
+			const { scope = "user", ...loadOptions } = pageOptions;
+			const state = await store.load(definition, registry);
+			const loaded = await loadOverview(scope === "tenant" ? state.tenant.document : state.document, definition, registry, ctx, loadOptions);
+			return {
+				...state,
+				loaded
+			};
+		},
+		async loadWidget(definition, registry, widget, ctx, loadOptions = {}) {
+			const state = await store.load(definition, registry);
+			const parsed = parseOverviewDocument({ widgets: [widget] });
+			const candidate = parsed.document.widgets[0];
+			if (!candidate || parsed.issues.length > 0) return {
+				ok: false,
+				reason: "invalid",
+				issues: parsed.issues
+			};
+			if (![...state.document.widgets, ...state.tenant.document.widgets].some((existing) => sameWidget(existing, candidate)) && !state.canCustomize.tenant && !state.canCustomize.user) return {
+				ok: false,
+				reason: "not_allowed"
+			};
+			const sanitized = sanitizeOverview({ widgets: [candidate] }, {
+				registry,
+				definition
+			});
+			if (sanitized.issues.length > 0) return {
+				ok: false,
+				reason: "invalid",
+				issues: sanitized.issues
+			};
+			const result = (await loadOverview(sanitized.document, definition, registry, ctx, loadOptions)).widgets[0];
+			if (!result) return {
+				ok: false,
+				reason: "invalid",
+				issues: []
+			};
+			if (result.status === "error") return {
+				ok: false,
+				reason: "load_failed",
+				code: result.error?.code ?? "load_failed"
+			};
+			return {
+				ok: true,
+				data: result.data
+			};
+		}
+	};
+	return store;
+}
+//#endregion
+export { CUSTOMIZE_OVERVIEW_PERMISSION, CUSTOMIZE_SHELL_PERMISSION, OVERVIEW_PREFERENCE_KIND, PERSONALIZE_OVERVIEW_PERMISSION, PERSONALIZE_SHELL_PERMISSION, PREFERENCE_KIND_PATTERN, PREFERENCE_PERMISSION_DEFINITIONS, PREFERENCE_SCOPES, PREFERENCE_SURFACE_PATTERN, PreferenceAccessError, SHELL_LAYOUT_PREFERENCE_KIND, TENANT_SCOPE_KEY, UiPreferenceRecord, UnknownPreferenceKindError, createOverviewStore, createPreferenceStore, createShellSettingsPreferences, ensureBuiltinPreferenceKinds, ensurePreferencePermissionsRegistered, getPreferenceKind, getPreferencePrincipal, listPreferenceKinds, overviewPreferenceKind, registerPreferenceKind, requirePreferenceKind, shellLayoutPreferenceKind, splitPermissionSlug, withTenantDefaults };
+
+//# sourceMappingURL=index.js.map