@hearthlog/runtime 0.0.0-stage → 0.1.1

package/src/store/tab-coordination.ts

@@ -0,0 +1,164 @@
+/**
+ * Coordination between tabs that share one local database.
+ *
+ * Tabs keep their own session state but write the same SQLite file, so three
+ * things need an agreement: who owns the live connection to Ledger, that sync
+ * and migrations do not overlap, and that a change one tab made reaches the
+ * others. Web Locks decide the first two, a BroadcastChannel carries the third.
+ * Without those APIs (server rendering, old browsers) every function degrades to
+ * a single tab's behavior.
+ */
+
+interface LockRequestOptions {
+    mode?: 'exclusive';
+    ifAvailable?: boolean;
+    signal?: AbortSignal;
+}
+
+export interface LockManagerLike {
+    request<T>(
+        name: string,
+        options: LockRequestOptions,
+        callback: (lock: unknown | null) => T | Promise<T>,
+    ): Promise<T>;
+}
+
+export interface TabScope {
+    tenantId: string;
+    logId: string;
+}
+
+/** What changed, so a tab refreshes only what it must. */
+export type TabChangeKind =
+    /** A local command was committed; pending counts and pages change. */
+    | 'commit'
+    /** Events from Ledger were ingested or acknowledged. */
+    | 'ingest'
+    /** The read model was rebuilt; in-memory caches are stale. */
+    | 'rebuild'
+    /** Entity type definitions or the schema changed; the registry is stale. */
+    | 'schema';
+
+export interface TabChange extends TabScope {
+    kind: TabChangeKind;
+}
+
+export function scopeKey(scope: TabScope): string {
+    return `${scope.tenantId}:${scope.logId}`;
+}
+
+export const realtimeLockName = (scope: TabScope) => `stor:realtime:${scopeKey(scope)}`;
+export const syncCycleLockName = (scope: TabScope) => `stor:sync:${scopeKey(scope)}`;
+export const SCHEMA_LOCK_NAME = 'stor:schema';
+
+function browserLocks(): LockManagerLike | null {
+    if (typeof navigator === 'undefined' || !('locks' in navigator)) return null;
+    return navigator.locks as unknown as LockManagerLike;
+}
+
+/** Run a task while no other tab holds the lock; waits its turn. */
+export async function withTabLock<T>(
+    name: string,
+    task: () => Promise<T>,
+    locks: LockManagerLike | null = browserLocks(),
+): Promise<T> {
+    if (!locks) return task();
+    return locks.request(name, { mode: 'exclusive' }, task);
+}
+
+/**
+ * Wait for a lock and keep it until the returned function is called. Calling it
+ * before the lock is granted withdraws the request. `onAcquired` runs once the
+ * lock is this tab's, and the lock is released if the tab closes.
+ */
+export function holdTabLock(
+    name: string,
+    onAcquired: () => void | Promise<void>,
+    locks: LockManagerLike | null = browserLocks(),
+): () => void {
+    if (!locks) {
+        void Promise.resolve(onAcquired());
+        return () => undefined;
+    }
+    const withdraw = new AbortController();
+    let release: () => void = () => undefined;
+    const held = new Promise<void>((resolve) => { release = resolve; });
+    locks.request(name, { mode: 'exclusive', signal: withdraw.signal }, async () => {
+        await onAcquired();
+        await held;
+    }).catch((error: unknown) => {
+        // Withdrawing a queued request rejects it; nothing else may fail here.
+        if (!(error instanceof DOMException && error.name === 'AbortError')) {
+            console.error('[Tabs] Lock request failed', error);
+        }
+    });
+    return () => {
+        withdraw.abort();
+        release();
+    };
+}
+
+const CHANNEL_NAME = 'stor:tab-changes';
+
+export interface TabChannel {
+    post(change: TabChange): void;
+    subscribe(listener: (change: TabChange) => void): () => void;
+    close(): void;
+}
+
+function isTabChange(value: unknown): value is TabChange {
+    if (!value || typeof value !== 'object') return false;
+    const change = value as Partial<TabChange>;
+    return typeof change.tenantId === 'string'
+        && typeof change.logId === 'string'
+        && (change.kind === 'commit' || change.kind === 'ingest'
+            || change.kind === 'rebuild' || change.kind === 'schema');
+}
+
+/** A channel never delivers to the tab that posted, so a handler cannot echo itself. */
+export function createTabChannel(name = CHANNEL_NAME): TabChannel {
+    if (typeof BroadcastChannel === 'undefined') {
+        return { post() {}, subscribe: () => () => undefined, close() {} };
+    }
+    const channel = new BroadcastChannel(name);
+    // Node keeps the process alive for an open channel; browsers have no unref.
+    (channel as unknown as { unref?: () => void }).unref?.();
+    const listeners = new Set<(change: TabChange) => void>();
+    channel.onmessage = (message: MessageEvent<unknown>) => {
+        if (!isTabChange(message.data)) return;
+        for (const listener of listeners) listener(message.data);
+    };
+    return {
+        post: (change) => channel.postMessage(change),
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        close() {
+            listeners.clear();
+            channel.close();
+        },
+    };
+}
+
+let shared: TabChannel | null = null;
+// Kept on globalThis so a hot reload does not leave two open channels.
+const globalForChannel = globalThis as unknown as { storTabChannel?: TabChannel };
+
+function sharedChannel(): TabChannel {
+    shared ??= globalForChannel.storTabChannel ??= createTabChannel();
+    return shared;
+}
+
+export function postTabChange(change: TabChange): void {
+    try {
+        sharedChannel().post(change);
+    } catch (error) {
+        // A closed channel must never fail the write that triggered the post.
+        console.warn('[Tabs] Could not notify other tabs', error);
+    }
+}
+
+export function onTabChange(listener: (change: TabChange) => void): () => void {
+    return sharedChannel().subscribe(listener);
+}

package/src/testing/e2e-seed.ts

@@ -0,0 +1,40 @@
+import { handleIncomingStoredEvents } from '../event/index.js';
+import type { StoredEvent } from '../ledger/types.js';
+import { notifyEventsChanged } from '../store/events.svelte.js';
+import { db } from '../db/index.js';
+import { sql } from 'kysely';
+
+export interface StorE2ESeedApi {
+    seedSyncedEvents(events: StoredEvent[]): Promise<{ hasNewEvents: boolean; newCount: number }>;
+    resetDatabase(): Promise<void>;
+}
+
+export function installE2ESeedHelper(): void {
+    if (import.meta.env.VITE_E2E !== '1' || typeof window === 'undefined') return;
+    window.__storE2E = {
+        async resetDatabase() {
+            const tables = await sql<{ name: string }>`
+                SELECT name
+                FROM sqlite_master
+                WHERE type = 'table' AND name NOT LIKE 'sqlite_%'
+            `.execute(db);
+            await sql.raw('PRAGMA foreign_keys = OFF').execute(db);
+            try {
+                await db.transaction().execute(async (tx) => {
+                    for (const { name } of tables.rows) {
+                        const quoted = `"${name.replace(/"/g, '""')}"`;
+                        await sql.raw(`DELETE FROM ${quoted}`).execute(tx);
+                    }
+                });
+            } finally {
+                await sql.raw('PRAGMA foreign_keys = ON').execute(db);
+            }
+        },
+        async seedSyncedEvents(events) {
+            const cloned = structuredClone(events).sort((left, right) => left.version - right.version);
+            const result = await handleIncomingStoredEvents(cloned);
+            notifyEventsChanged();
+            return result;
+        },
+    };
+}

package/src/testing/local-database.ts

@@ -0,0 +1,120 @@
+import { DatabaseSync, type SQLInputValue } from 'node:sqlite';
+import { Kysely, SqliteDialect } from 'kysely';
+import type { Database } from '../db/index.js';
+import { getEntityDDLForTables } from '#generated/schema';
+
+/** Independent SQLite stores for persistence/convergence tests; no browser globals. */
+export function createLocalDatabase(tables: readonly string[] = ["calendar_events"]) {
+    const sqlite = new DatabaseSync(':memory:');
+    sqlite.exec(`
+            CREATE TABLE IF NOT EXISTS "raw_events" (
+                "id" TEXT NOT NULL,
+                "tenant_id" TEXT NOT NULL DEFAULT 'legacy-unassigned',
+                "log_id" TEXT NOT NULL DEFAULT 'legacy-unassigned',
+                "local_batch_id" TEXT NOT NULL,
+                "local_sequence" INTEGER NOT NULL DEFAULT 0,
+                action_id TEXT, action_index INTEGER, action_size INTEGER, actor TEXT,
+                "type" TEXT NOT NULL,
+                "timestamp" INTEGER NOT NULL,
+                "payload" TEXT NOT NULL,
+                "entity_id" TEXT,
+                "entity_version" INTEGER,
+                "log_version" INTEGER,
+                "sync_state" TEXT NOT NULL DEFAULT 'pending',
+                "projection_state" TEXT NOT NULL DEFAULT 'effective',
+                "rejection_code" TEXT,
+                "rejection_detail" TEXT,
+                "is_tombstoned" INTEGER DEFAULT 0,
+                "created_at" TEXT DEFAULT (datetime('now')),
+                PRIMARY KEY ("tenant_id", "log_id", "id")
+            );
+
+
+            CREATE TABLE IF NOT EXISTS "entity_versions" (
+                "tenant_id" TEXT NOT NULL,
+                "log_id" TEXT NOT NULL,
+                "entity_id" TEXT NOT NULL,
+                "current_version" INTEGER NOT NULL,
+                "log_version" INTEGER NOT NULL,
+                "updated_at" INTEGER NOT NULL,
+                PRIMARY KEY ("tenant_id", "log_id", "entity_id")
+            );
+
+
+            CREATE TABLE IF NOT EXISTS "local_batches" (
+                "id" TEXT PRIMARY KEY,
+                "tenant_id" TEXT NOT NULL,
+                "log_id" TEXT NOT NULL,
+                "status" TEXT NOT NULL DEFAULT 'pending',
+                "replacement_for" TEXT,
+                "created_at" TEXT DEFAULT (datetime('now')),
+                "updated_at" TEXT DEFAULT (datetime('now'))
+            );
+
+
+            CREATE TABLE IF NOT EXISTS "outbox_operations" (
+                "id" TEXT PRIMARY KEY,
+                "request_id" TEXT NOT NULL,
+                "tenant_id" TEXT NOT NULL,
+                "log_id" TEXT NOT NULL,
+                "batch_id" TEXT NOT NULL,
+                "request_body" TEXT NOT NULL,
+                "request_hash" TEXT NOT NULL,
+                "status" TEXT NOT NULL DEFAULT 'pending',
+                "retry_count" INTEGER NOT NULL DEFAULT 0,
+                "rebase_count" INTEGER NOT NULL DEFAULT 0,
+                "last_error_code" TEXT,
+                "last_error_message" TEXT,
+                "superseded_by" TEXT,
+                "next_retry_at" TEXT,
+                "created_at" TEXT DEFAULT (datetime('now')),
+                "updated_at" TEXT DEFAULT (datetime('now')),
+                UNIQUE ("tenant_id", "log_id", "request_id")
+            );
+
+
+            CREATE TABLE IF NOT EXISTS "outbox_operation_items" (
+                "operation_id" TEXT NOT NULL,
+                "event_id" TEXT NOT NULL,
+                "ordinal" INTEGER NOT NULL,
+                PRIMARY KEY ("operation_id", "ordinal")
+            );
+
+
+            CREATE TABLE IF NOT EXISTS "log_sync_state" (
+                "tenant_id" TEXT NOT NULL,
+                "log_id" TEXT NOT NULL,
+                "downloaded_head_version" INTEGER NOT NULL DEFAULT 0,
+                "projected_head_version" INTEGER NOT NULL DEFAULT 0,
+                "last_synced_at" TEXT,
+                PRIMARY KEY ("tenant_id", "log_id")
+            );
+
+
+            CREATE TABLE IF NOT EXISTS "resolution_actions" (
+                "id" TEXT PRIMARY KEY,
+                "tenant_id" TEXT NOT NULL,
+                "log_id" TEXT NOT NULL,
+                "batch_id" TEXT NOT NULL,
+                "action" TEXT NOT NULL,
+                "details" TEXT,
+                "created_at" TEXT DEFAULT (datetime('now'))
+            );
+
+    CREATE TABLE sync_logs (id TEXT PRIMARY KEY, timestamp INTEGER, type TEXT, message TEXT, details TEXT);
+    `);
+    for (const ddl of getEntityDDLForTables(new Set(tables))) sqlite.exec(ddl);
+    const database = new Kysely<Database>({ dialect: new SqliteDialect({ database: {
+        close: () => sqlite.close(),
+        prepare(query: string) {
+            const statement = sqlite.prepare(query);
+            return {
+                reader: /^\s*(?:PRAGMA|SELECT|WITH|EXPLAIN)/i.test(query),
+                all: (params: readonly unknown[]) => statement.all(...params as SQLInputValue[]),
+                run: (params: readonly unknown[]) => statement.run(...params as SQLInputValue[]),
+                iterate: (params: readonly unknown[]) => statement.iterate(...params as SQLInputValue[]),
+            };
+        },
+    } }) });
+    return { database, sqlite };
+}

package/src/testing/projection-database.ts

@@ -0,0 +1,105 @@
+import { DatabaseSync, type SQLInputValue } from 'node:sqlite';
+import { Kysely, SqliteDialect } from 'kysely';
+import type { Database } from '../db/index.js';
+import { getEntityDDLForTables } from '#generated/schema';
+import { buildBulkProjectionSQL, projectEntitySet, PROJECTION_CONFIGS } from '../event/projection-builder.js';
+
+export type TestScope = { tenantId: string; logId: string };
+
+export interface TestEvent {
+    id: string;
+    type: string;
+    timestamp: number;
+    payload: Record<string, unknown>;
+    entityId: string | null;
+    entityVersion: number | null;
+    logVersion: number | null;
+    sequence?: number;
+    syncState?: 'pending' | 'synced';
+    projectionState?: 'effective' | 'rejected';
+    tombstoned?: boolean;
+}
+
+/**
+ * An in-memory database for projection tests: `raw_events`, the read-model tables of the entities
+ * named, and optionally a copy of those tables in a `history` schema. No browser globals.
+ * Modules reach it through `@hearthlog/sdk/testing`; it never exposes the app's database type.
+ */
+export function createProjectionTestDatabase(options: { tables: readonly string[]; scope?: TestScope; history?: boolean }) {
+    const scope = options.scope ?? { tenantId: 'tenant-1', logId: 'log-1' };
+    const sqlite = new DatabaseSync(':memory:');
+    sqlite.exec(`
+        CREATE TABLE raw_events (
+            id TEXT NOT NULL, tenant_id TEXT NOT NULL, log_id TEXT NOT NULL,
+            local_batch_id TEXT NOT NULL, local_sequence INTEGER NOT NULL,
+            type TEXT NOT NULL, timestamp INTEGER NOT NULL, payload TEXT NOT NULL,
+            entity_id TEXT, entity_version INTEGER, log_version INTEGER,
+            sync_state TEXT NOT NULL, projection_state TEXT NOT NULL,
+            rejection_code TEXT, rejection_detail TEXT, is_tombstoned INTEGER NOT NULL DEFAULT 0,
+            created_at TEXT DEFAULT (datetime('now')),
+            PRIMARY KEY (tenant_id, log_id, id)
+        );
+    `);
+    for (const ddl of getEntityDDLForTables(new Set(options.tables))) sqlite.exec(ddl);
+    if (options.history) {
+        sqlite.exec(`ATTACH DATABASE ':memory:' AS history;`);
+        for (const table of options.tables) sqlite.exec(`CREATE TABLE history."${table}" AS SELECT * FROM main."${table}" WHERE 0;`);
+    }
+    const database = new Kysely<Database>({
+        dialect: new SqliteDialect({
+            database: {
+                close: () => sqlite.close(),
+                prepare(query: string) {
+                    const statement = sqlite.prepare(query);
+                    return {
+                        reader: /^\s*(?:PRAGMA|SELECT|WITH|EXPLAIN)\b/i.test(query),
+                        all: (parameters: ReadonlyArray<unknown>) => statement.all(...(parameters as SQLInputValue[])),
+                        run: (parameters: ReadonlyArray<unknown>) => statement.run(...(parameters as SQLInputValue[])),
+                        iterate: (parameters: ReadonlyArray<unknown>) => statement.iterate(...(parameters as SQLInputValue[])),
+                    };
+                },
+            },
+        }),
+    });
+    const insert = sqlite.prepare(`
+        INSERT INTO raw_events (
+            id, tenant_id, log_id, local_batch_id, local_sequence, type, timestamp,
+            payload, entity_id, entity_version, log_version, sync_state, projection_state, is_tombstoned
+        ) VALUES (?, ?, ?, 'batch', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    let sequence = 0;
+    const config = (entity: string) => {
+        const found = PROJECTION_CONFIGS[entity];
+        if (!found) throw new Error(`No projection config for entity "${entity}"`);
+        return found;
+    };
+    return {
+        scope,
+        sqlite,
+        /** Appends one event to `raw_events` (accepted and effective unless said otherwise). */
+        addEvent(event: TestEvent): void {
+            sequence += 1;
+            insert.run(
+                event.id, scope.tenantId, scope.logId, event.sequence ?? sequence, event.type, event.timestamp,
+                JSON.stringify(event.payload), event.entityId, event.entityVersion, event.logVersion,
+                event.syncState ?? 'synced', event.projectionState ?? 'effective', event.tombstoned ? 1 : 0,
+            );
+        },
+        /** Projects the given entities from `raw_events` into their read-model tables. */
+        async project(entity: string, entityIds: string[]): Promise<void> {
+            await database.transaction().execute((tx) => projectEntitySet(config(entity), entityIds, tx, scope));
+        },
+        /** Rebuilds one entity's table from every event, optionally as of a log version into `history`. */
+        async rebuild(entity: string, boundary?: { version: number; schema: 'history' }): Promise<void> {
+            const query = boundary
+                ? buildBulkProjectionSQL(config(entity), scope, { boundary: { kind: 'log-version', version: boundary.version }, target: { schema: boundary.schema } })
+                : buildBulkProjectionSQL(config(entity), scope);
+            await query.execute(database);
+        },
+        async destroy(): Promise<void> {
+            await database.destroy();
+        },
+    };
+}
+
+export type ProjectionTestDatabase = ReturnType<typeof createProjectionTestDatabase>;

package/src/testing/test-entities.ts

@@ -0,0 +1,28 @@
+import type { EntityDefinition } from '@hearthlog/contracts/event/entity-definitions';
+
+/**
+ * An entity that exists only in tests, for rules the core's own entity cannot show: a numeric field
+ * (`test_amount`, in the always-enabled calendar feature). A test adds it with
+ *
+ *     vi.mock('@hearthlog/contracts/event/entity-definitions', async (importOriginal) =>
+ *         (await import('./test-entities.js')).withTestEntities(await importOriginal()));
+ *
+ * so the registry, validation, and projection configs all see it. It has no generated table: a test
+ * that projects it creates the table itself.
+ */
+export const TEST_ENTITY_DEFINITIONS: EntityDefinition[] = [
+    {
+        name: 'test_amount',
+        feature: 'calendar',
+        displayName: 'Test amount',
+        table: 'test_amounts',
+        fields: [
+            { name: 'name', type: 'string', payloadKey: 'name', required: true },
+            { name: 'amount', type: 'number', payloadKey: 'amount', required: true },
+        ],
+    },
+];
+
+export function withTestEntities<T extends { ENTITY_DEFINITIONS: EntityDefinition[] }>(original: T): T {
+    return { ...original, ENTITY_DEFINITIONS: [...original.ENTITY_DEFINITIONS, ...TEST_ENTITY_DEFINITIONS] };
+}

package/src/theme/appearance.svelte.ts

@@ -0,0 +1,111 @@
+import type { ResolvedTheme, ThemePreference } from "@hearthlog/contracts/tenant/theme";
+
+export const APPEARANCE_EVENT = "stor:appearance-change";
+
+export function appearanceStorageKey(tenantId: string): string {
+    return `stor:appearance:${tenantId}`;
+}
+
+export function parseThemePreference(value: unknown): ThemePreference {
+    return value === "light" || value === "dark" || value === "system"
+        ? value
+        : "system";
+}
+
+export function resolveTheme(
+    preference: ThemePreference,
+    systemPrefersDark: boolean,
+): ResolvedTheme {
+    return preference === "system"
+        ? systemPrefersDark
+            ? "dark"
+            : "light"
+        : preference;
+}
+
+function initialPreference(): ThemePreference {
+    if (typeof document === "undefined") return "system";
+    return parseThemePreference(document.documentElement.dataset.appearance);
+}
+
+function initialTheme(): ResolvedTheme {
+    if (typeof document === "undefined") return "light";
+    return document.documentElement.dataset.theme === "dark" ? "dark" : "light";
+}
+
+let preference = $state<ThemePreference>(initialPreference());
+let resolved = $state<ResolvedTheme>(initialTheme());
+let storageKey = "";
+let mediaQuery: MediaQueryList | null = null;
+let removeListeners: (() => void) | null = null;
+
+function applyResolvedTheme(next: ResolvedTheme): void {
+    resolved = next;
+    document.documentElement.dataset.theme = next;
+    document.documentElement.dataset.appearance = preference;
+    document.documentElement.style.colorScheme = next;
+    const themeColor = getComputedStyle(document.documentElement)
+        .getPropertyValue("--stor-theme-color")
+        .trim();
+    const meta = document.querySelector<HTMLMetaElement>('meta[name="theme-color"]');
+    if (meta && themeColor) meta.content = themeColor;
+    window.dispatchEvent(new CustomEvent(APPEARANCE_EVENT, {
+        detail: { preference, resolved: next },
+    }));
+}
+
+function applyPreference(next: ThemePreference, persist: boolean): void {
+    preference = next;
+    if (persist && storageKey) {
+        try {
+            localStorage.setItem(storageKey, next);
+        } catch {
+            // The in-memory selection still works when storage is unavailable.
+        }
+    }
+    applyResolvedTheme(resolveTheme(next, mediaQuery?.matches ?? false));
+}
+
+export function initializeAppearance(tenantId: string): () => void {
+    removeListeners?.();
+    storageKey = appearanceStorageKey(tenantId);
+    mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+    let stored: unknown = document.documentElement.dataset.appearance;
+    try {
+        stored = localStorage.getItem(storageKey);
+    } catch {
+        // Use the preference resolved by the boot script.
+    }
+    applyPreference(parseThemePreference(stored), false);
+
+    const handleSystemChange = (event: MediaQueryListEvent) => {
+        if (preference === "system") {
+            applyResolvedTheme(event.matches ? "dark" : "light");
+        }
+    };
+    const handleStorage = (event: StorageEvent) => {
+        if (event.key === storageKey) {
+            applyPreference(parseThemePreference(event.newValue), false);
+        }
+    };
+    mediaQuery.addEventListener("change", handleSystemChange);
+    window.addEventListener("storage", handleStorage);
+    removeListeners = () => {
+        mediaQuery?.removeEventListener("change", handleSystemChange);
+        window.removeEventListener("storage", handleStorage);
+        removeListeners = null;
+    };
+    return removeListeners;
+}
+
+export const appearance = {
+    get preference(): ThemePreference {
+        return preference;
+    },
+    get resolved(): ResolvedTheme {
+        return resolved;
+    },
+    setPreference(next: ThemePreference): void {
+        applyPreference(next, true);
+    },
+};

package/src/utils/address.ts

@@ -0,0 +1,5 @@
+/** A page number or size read from the address; `fallback` when it is missing or not a whole number above zero. */
+export function parsePositiveInt(value: string | null, fallback: number): number {
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}

package/src/utils/async.ts

@@ -0,0 +1,30 @@
+/**
+ * Async Utilities
+ */
+
+/**
+ * Wraps a promise with a timeout.
+ * If the promise does not resolve within the specified milliseconds, it rejects with an error.
+ * 
+ * @param promise The promise to wrap
+ * @param ms Timeout in milliseconds
+ * @param errorMessage Optional error message
+ */
+export function withTimeout<T>(
+    promise: Promise<T>,
+    ms: number,
+    errorMessage = 'Operation timed out'
+): Promise<T> {
+    const timeout = new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error(errorMessage)), ms)
+    );
+
+    return Promise.race([promise, timeout]);
+}
+
+/**
+ * Creates a promise that resolves after a specified delay.
+ */
+export function delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/utils/long-press.ts

@@ -0,0 +1,70 @@
+/**
+ * Press and hold on touch: calls `onLongPress` with the element matching
+ * `selector` after `delay` ms unless the finger moved more than 8 px, then
+ * swallows the click that follows so the press does not also open the row.
+ * A mouse never long-presses; desktop rows keep their checkboxes.
+ */
+export function longPress(
+    node: HTMLElement,
+    options: { selector: string; onLongPress: (element: HTMLElement) => void; delay?: number },
+) {
+    let current = options;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let start = { x: 0, y: 0 };
+    let fired = false;
+
+    const cancel = () => clearTimeout(timer);
+
+    function down(event: PointerEvent): void {
+        if (event.pointerType === 'mouse') return;
+        const target = (event.target as HTMLElement).closest<HTMLElement>(current.selector);
+        if (!target || !node.contains(target)) return;
+        fired = false;
+        start = { x: event.clientX, y: event.clientY };
+        cancel();
+        timer = setTimeout(() => {
+            fired = true;
+            // A press that never ends in a click (the finger slid off) must not eat a later tap.
+            setTimeout(() => { fired = false; }, 800);
+            navigator.vibrate?.(10);
+            current.onLongPress(target);
+        }, current.delay ?? 450);
+    }
+
+    function move(event: PointerEvent): void {
+        if (Math.hypot(event.clientX - start.x, event.clientY - start.y) > 8) cancel();
+    }
+
+    function click(event: MouseEvent): void {
+        if (!fired) return;
+        fired = false;
+        event.preventDefault();
+        event.stopPropagation();
+    }
+
+    function contextMenu(event: Event): void {
+        if ((event.target as HTMLElement).closest(current.selector)) event.preventDefault();
+    }
+
+    node.addEventListener('pointerdown', down);
+    node.addEventListener('pointermove', move);
+    node.addEventListener('pointerup', cancel);
+    node.addEventListener('pointercancel', cancel);
+    node.addEventListener('scroll', cancel, true);
+    node.addEventListener('click', click, true);
+    node.addEventListener('contextmenu', contextMenu);
+
+    return {
+        update(next: typeof options) { current = next; },
+        destroy() {
+            cancel();
+            node.removeEventListener('pointerdown', down);
+            node.removeEventListener('pointermove', move);
+            node.removeEventListener('pointerup', cancel);
+            node.removeEventListener('pointercancel', cancel);
+            node.removeEventListener('scroll', cancel, true);
+            node.removeEventListener('click', click, true);
+            node.removeEventListener('contextmenu', contextMenu);
+        },
+    };
+}