@livenetworks/ashlar 1.6.0 → 2.0.0

package/{js → components}/ln-data-store/src/ln-data-store.js

@@ -1,4 +1,6 @@
-import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, decryptData } from '../../ln-core';
+import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, decryptData, defineAttrs, attrSpec, attrInt, attrBool, attrList } from '../../ln-core';
+import { createWindowIndex } from './window-index.js';
+import { aggregateRecords, decorateRecords, filterRecords, queryRecords } from './data-store-model.js';
 
 (function () {
 	const DOM_SELECTOR = 'data-ln-data-store';
@@ -6,6 +8,29 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 
 	if (window[DOM_ATTRIBUTE] !== undefined) return;
 
+	// ─── Custom Attribute Readers ───────────────────────────
+	// 'never' / '-1' mean "no staleness", everything unparsable means the default.
+	function _readStale(el, name, fallback) {
+		const raw = el.getAttribute(name);
+		if (raw === 'never' || raw === '-1') return -1;
+		const parsed = parseInt(raw, 10);
+		return isNaN(parsed) ? fallback : parsed;
+	}
+
+	// ─── Attribute Contract (SSOT) ──────────────────────────
+	const ATTRIBUTES = {
+		'data-ln-data-store':                  { type: 'marker', effect: _markFrozen, description: 'Identifies the element as a data-store definition container' },
+		'data-ln-data-store-indexes':          { type: 'list', effect: _markFrozen, description: 'Comma-separated index field names for the IndexedDB store' },
+		'data-ln-data-store-stale':            { prop: '_staleThreshold', type: 'integer', read: _readStale, fallback: 300, description: 'Cache staleness threshold in seconds, or -1/never' },
+		'data-ln-data-store-search-fields':    { prop: '_searchFields', type: 'list', read: attrList, description: 'Record fields to index for client-side search' },
+		'data-ln-data-store-no-local-query':   { prop: 'noLocalQuery', type: 'boolean', read: attrBool, description: 'Bypasses local IndexedDB query resolution, forcing remote fetching' },
+		'data-ln-data-store-window':           { prop: '_windowSize', type: 'integer', read: attrInt, fallback: 1000, min: 10, effect: _applyWindowSize, description: 'Virtual scrolling cache window size in records' },
+		'data-ln-data-store-window-page':      { prop: '_windowPageSize', type: 'integer', read: attrInt, fallback: 200, min: 5, effect: _applyWindowPageSize, description: 'Virtual scrolling slice page size' },
+		'data-ln-data-store-frozen':           { type: 'marker', description: 'Applied at runtime to indicate store schema is locked in IndexedDB' }
+	};
+
+	const ATTR_SPEC = attrSpec(ATTRIBUTES);
+
 	const DB_NAME = 'ln_app_cache';
 	const META_STORE = '_meta';
 	const SCHEMA_VERSION = '1.0';
@@ -25,7 +50,7 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 	function _getRequiredStores() {
 		const required = {};
 		for (const el of document.querySelectorAll(`[${DOM_SELECTOR}]`)) {
-			const name = el.getAttribute(DOM_SELECTOR);
+			const name = el.id;
 			if (name) {
 				const indexAttr = el.getAttribute('data-ln-data-store-indexes') || '';
 				required[name] = {
@@ -134,16 +159,14 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 		if (!encryptedPayload || !encryptedPayload.encrypted) return record;
 
 		return {
-			id: recordId,
-			encrypted: true,
-			iv: encryptedPayload.iv,
-			data: encryptedPayload.data
+			...encryptedPayload,
+			id: recordId
 		};
 	}
 
 	async function _decryptRecord(record) {
 		if (!record || !record.encrypted || !getCryptoKey()) return record;
-		return decryptData(record);
+		return decryptData(record, { silent: true });
 	}
 
 	// ─── IndexedDB CRUD Helpers ────────────────────────────
@@ -165,15 +188,59 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 		.then(records => getCryptoKey() ? Promise.all(records.map(r => _decryptRecord(r))) : records);
 
 	const _getRecord = (storeName, id) => _tx(storeName, 'readonly')
-		.then(store => store ? _idbRequest(store.get(id)) : null)
+		.then(store => {
+			if (!store) return null;
+			return _idbRequest(store.get(id)).then(res => {
+				if (res !== undefined) return res;
+				if (typeof id === 'string' && id.trim() !== '' && !isNaN(Number(id))) {
+					return _idbRequest(store.get(Number(id)));
+				}
+				if (typeof id === 'number') {
+					return _idbRequest(store.get(String(id)));
+				}
+				return null;
+			});
+		})
 		.then(record => record ? _decryptRecord(record) : null);
 
+	const _getMultipleRecords = (storeName, ids) => _getDb().then(db => {
+		if (!db) return [];
+		const tx = db.transaction(storeName, 'readonly');
+		const store = tx.objectStore(storeName);
+		const promises = ids.map(id => _idbRequest(store.get(id)).then(res => {
+			if (res !== undefined) return res;
+			if (typeof id === 'string' && id.trim() !== '' && !isNaN(Number(id))) {
+				return _idbRequest(store.get(Number(id)));
+			}
+			if (typeof id === 'number') {
+				return _idbRequest(store.get(String(id)));
+			}
+			return null;
+		}));
+		return Promise.all(promises).then(records => {
+			if (getCryptoKey()) {
+				return Promise.all(records.map(r => r ? _decryptRecord(r) : null));
+			}
+			return records;
+		});
+	});
+
 	const _putRecord = (storeName, record) => {
 		const prepPromise = getCryptoKey() ? _encryptRecord(record) : Promise.resolve(record);
 		return prepPromise.then(prepped => _tx(storeName, 'readwrite').then(store => store ? _idbRequest(store.put(prepped)) : null));
 	};
 
-	const _deleteRecord = (storeName, id) => _tx(storeName, 'readwrite').then(store => store ? _idbRequest(store.delete(id)) : null);
+	const _deleteRecord = (storeName, id) => _tx(storeName, 'readwrite').then(store => {
+		if (!store) return null;
+		return _idbRequest(store.delete(id)).then(() => {
+			if (typeof id === 'string' && id.trim() !== '' && !isNaN(Number(id))) {
+				return _idbRequest(store.delete(Number(id)));
+			}
+			if (typeof id === 'number') {
+				return _idbRequest(store.delete(String(id)));
+			}
+		});
+	});
 	const _clearStore = storeName => _tx(storeName, 'readwrite').then(store => store ? _idbRequest(store.clear()) : null);
 	const _countRecords = storeName => _tx(storeName, 'readonly').then(store => store ? _idbRequest(store.count()) : 0);
 
@@ -190,23 +257,45 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 
 	function _component(dom) {
 		this.dom = dom;
-		this._name = dom.getAttribute(DOM_SELECTOR);
+		this._name = dom.id;
+		if (!this._name) console.warn('[ln-data-store] missing id — the store cannot be addressed', dom);
 
-		const staleAttr = dom.getAttribute('data-ln-data-store-stale');
-		const _parsed = parseInt(staleAttr, 10);
-		this._staleThreshold = (staleAttr === 'never' || staleAttr === '-1') ? -1 : (isNaN(_parsed) ? 300 : _parsed);
-
-		const searchAttr = dom.getAttribute('data-ln-data-store-search-fields') || '';
-		this._searchFields = searchAttr.split(',').map(s => s.trim()).filter(Boolean);
+		defineAttrs(this, dom, ATTR_SPEC);
 
 		this._handlers = null;
 
 		this.isLoaded = false;
+		// Two different questions that shared one flag until they were split.
+		// isLoaded: a full sync has landed, so the cache is authoritative and sync
+		// staleness may be judged against it. canServe: records are held that can
+		// answer a read. A page fetch grants the second without granting the first.
+		this.canServe = false;
 		this.isInitialized = false;
 		this.initializationError = null;
 		this.hasCache = false;
 		this.isSyncing = false;
 		this.lastSyncedAt = null;
+		this.query = { filters: {}, search: '', sort: null };
+		if (dom.hasAttribute('data-ln-data-store-window')) {
+			this._windowIndex = createWindowIndex({
+				windowSize: this._windowSize,
+				pageSize: this._windowPageSize,
+				requestPage: (offset, limit, query) => {
+					dispatch(this.dom, 'ln-data-store:request-page', {
+						store: this._name,
+						offset: offset,
+						limit: limit,
+						query: query,
+						queryGen: this._windowIndex.queryGen
+					});
+				}
+			});
+		} else {
+			this._windowIndex = null;
+		}
+		this.windowed = this._windowIndex !== null;
+		// Opt out of answering reads from the cache: queries wait for the server.
+		// Read live off the host — see the effects map at registration.
 		this.totalCount = 0;
 		this.presenters = null;
 		this._mutationChain = Promise.resolve();
@@ -238,6 +327,50 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 		for (const [event, fn] of Object.entries(self._handlers)) {
 			self.dom.addEventListener(`ln-data-store:request-${event}`, fn);
 		}
+
+		self._queryHandlers = {
+			'ln-search:change': e => {
+				e.preventDefault();
+				const term = (e.detail && e.detail.term != null) ? e.detail.term : '';
+				if (term === self.query.search) return;
+				self.query.search = term;
+				_emitQueryChanged(self);
+			},
+			'ln-filter:change': e => {
+				e.preventDefault();
+				const key = e.detail && e.detail.key;
+				if (!key) return;
+				const values = (e.detail.values || []).slice();
+				// Same no-op guard the search and sort handlers carry: a reset of a
+				// filter that was never set is not a query change, and clear-all
+				// resets every filter control on the page at once.
+				const prev = self.query.filters[key];
+				const unchanged = prev
+					? (prev.length === values.length && prev.every((v, i) => v === values[i]))
+					: !values.length;
+				if (unchanged) return;
+				if (values.length) self.query.filters[key] = values;
+				else delete self.query.filters[key];
+				_emitQueryChanged(self);
+			},
+			'ln-sort:change': e => {
+				e.preventDefault();
+				const field = e.detail && e.detail.field;
+				const direction = e.detail && e.detail.direction;
+				// ln-sort emits direction 'none' to mean "sort removed" — a truthy
+				// string, so it has to be excluded explicitly or it travels to the
+				// server as sort_dir=none.
+				const next = (direction && direction !== 'none') ? { field, direction } : null;
+				const prev = self.query.sort;
+				const unchanged = (!prev && !next) || (prev && next && prev.field === next.field && prev.direction === next.direction);
+				if (unchanged) return;
+				self.query.sort = next;
+				_emitQueryChanged(self);
+			}
+		};
+		for (const [event, fn] of Object.entries(self._queryHandlers)) {
+			self.dom.addEventListener(event, fn);
+		}
 	}
 
 	function _queueMutation(self, action, detail, operation) {
@@ -252,16 +385,22 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 		return self._mutationChain;
 	}
 
-	function _persistMutationMeta(self) {
+	function _persistMutationMeta(self, deltaCount = 0) {
 		return _countRecords(self._name).then(count => {
-			self.totalCount = count;
+			if (self._windowIndex || self.windowed) {
+				const current = self.totalCount != null ? self.totalCount : count;
+				self.totalCount = Math.max(0, current + deltaCount);
+			} else {
+				self.totalCount = count;
+			}
 			self.hasCache = true;
 			self.isLoaded = true;
+			self.canServe = true;
 			return _setMeta(self._name, {
 				schema_version: SCHEMA_VERSION,
 				last_synced_at: self.lastSyncedAt,
 				has_cache: true,
-				record_count: count
+				record_count: self.totalCount
 			});
 		});
 	}
@@ -271,7 +410,7 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 	function _handleCreateRequest(self, { tempId, data = {}, requestId } = {}) {
 		const record = { ...data, id: tempId };
 
-		return _putRecord(self._name, record).then(() => _persistMutationMeta(self)).then(() => {
+		return _putRecord(self._name, record).then(() => _persistMutationMeta(self, 1)).then(() => {
 			dispatch(self.dom, 'ln-data-store:created', { store: self._name, record, tempId, requestId });
 		});
 	}
@@ -280,16 +419,17 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 		return _getRecord(self._name, id).then(existing => {
 			if (!existing) throw new Error(`Record not found: ${id}`);
 
-			const updated = { ...existing, ...data };
+			const canonicalId = existing.id;
+			const updated = { ...existing, ...data, id: canonicalId };
 			const newId = data.id;
-			const isRekey = newId !== undefined && newId !== id;
+			const isRekey = newId !== undefined && newId !== canonicalId;
 
 			const write = isRekey
-				? _rekeyRecord(self._name, id, updated)
+				? _rekeyRecord(self._name, canonicalId, { ...updated, id: newId })
 				: _putRecord(self._name, updated);
 
-			return write.then(() => _persistMutationMeta(self)).then(() => {
-				dispatch(self.dom, 'ln-data-store:updated', { store: self._name, record: updated, previous: existing, requestId });
+			return write.then(() => _persistMutationMeta(self, 0)).then(() => {
+				dispatch(self.dom, 'ln-data-store:updated', { store: self._name, record: isRekey ? { ...updated, id: newId } : updated, previous: existing, requestId });
 			});
 		});
 	}
@@ -301,8 +441,9 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 				return;
 			}
 
-			return _deleteRecord(self._name, id).then(() => _persistMutationMeta(self)).then(() => {
-				dispatch(self.dom, 'ln-data-store:deleted', { store: self._name, id, requestId });
+			const canonicalId = existing.id;
+			return _deleteRecord(self._name, canonicalId).then(() => _persistMutationMeta(self, -1)).then(() => {
+				dispatch(self.dom, 'ln-data-store:deleted', { store: self._name, id: canonicalId, requestId });
 			});
 		});
 	}
@@ -316,7 +457,7 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 		return Promise.all(ids.map(id => _getRecord(self._name, id))).then(records => {
 			const savedIds = records.filter(Boolean).map(r => r.id);
 
-			return _deleteBulk(self._name, savedIds).then(() => _persistMutationMeta(self)).then(() => {
+			return _deleteBulk(self._name, savedIds).then(() => _persistMutationMeta(self, -savedIds.length)).then(() => {
 				dispatch(self.dom, 'ln-data-store:deleted', { store: self._name, ids: savedIds, requestId });
 			});
 		});
@@ -347,6 +488,7 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 
 				if (self.hasCache) {
 					self.isLoaded = true;
+					self.canServe = true;
 					dispatch(self.dom, 'ln-data-store:ready', { store: self._name, count: self.totalCount, source: 'cache' });
 				}
 
@@ -368,6 +510,7 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 		}).catch(error => {
 			self.isInitialized = true;
 			self.isLoaded = false;
+			self.canServe = false;
 			self.hasCache = false;
 			self.isSyncing = false;
 			self.initializationError = error;
@@ -412,7 +555,14 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 			return new Promise((resolve, reject) => {
 				const tx = db.transaction(storeName, 'readwrite');
 				const store = tx.objectStore(storeName);
-				ids.forEach(id => store.delete(id));
+				ids.forEach(id => {
+					store.delete(id);
+					if (typeof id === 'string' && id.trim() !== '' && !isNaN(Number(id))) {
+						store.delete(Number(id));
+					} else if (typeof id === 'number') {
+						store.delete(String(id));
+					}
+				});
 				tx.oncomplete = () => resolve();
 				tx.onerror = () => reject(tx.error);
 			});
@@ -434,104 +584,182 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 		}));
 	}
 
-	// ─── Query Engine (In-Memory over Cache) ───────────────
-
 	const _collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
 
-	function _sort(records, sort) {
-		if (!sort || !sort.field) return records;
-		const { field, direction } = sort;
-		const desc = direction === 'desc';
-
-		return [...records].sort((a, b) => {
-			const va = a[field];
-			const vb = b[field];
-
-			if (va == null && vb == null) return 0;
-			if (va == null) return desc ? 1 : -1;
-			if (vb == null) return desc ? -1 : 1;
-
-			const result = (typeof va === 'string' && typeof vb === 'string')
-				? _collator.compare(va, vb)
-				: (va < vb ? -1 : va > vb ? 1 : 0);
-
-			return desc ? -result : result;
-		});
+	function _filterKeys(filters) {
+		if (!filters) return [];
+		return Object.keys(filters).filter(k => Array.isArray(filters[k]) && filters[k].length > 0);
 	}
 
-	function _filter(records, filters) {
-		if (!filters) return records;
-		const keys = Object.keys(filters).filter(k => Array.isArray(filters[k]) && filters[k].length > 0);
-		if (!keys.length) return records;
+	function _matchesFilters(record, keys, filters) {
+		return keys.every(field => filters[field].map(String).includes(String(record[field])));
+	}
 
-		return records.filter(record =>
-			keys.every(field => filters[field].map(String).includes(String(record[field])))
-		);
+	function _tokenize(query) {
+		return String(query || '').toLowerCase().split(/\s+/).filter(Boolean);
 	}
 
-	function _search(records, query, searchFields) {
-		if (!query || !searchFields || !searchFields.length) return records;
-		const lower = query.toLowerCase();
-		return records.filter(record =>
+	function _matchesTokens(record, tokens, searchFields) {
+		return tokens.every(token =>
 			searchFields.some(field => {
 				const val = record[field];
-				return val != null && String(val).toLowerCase().includes(lower);
+				return val != null && String(val).toLowerCase().includes(token);
 			})
 		);
 	}
 
 	function _aggregate(records, field, fn) {
-		if (!records.length) return 0;
-		if (fn === 'count') return records.length;
+		return aggregateRecords(records, field, fn);
+	}
+
+	function _decorate(self, records) {
+		return decorateRecords(records, self.presenters && self.presenters.computed);
+	}
 
-		const numbers = records.map(r => parseFloat(r[field])).filter(v => !isNaN(v));
-		const sum = numbers.reduce((a, b) => a + b, 0);
+	// ─── Public CRUD & Sync APIs ───────────────────────────
 
-		if (fn === 'sum') return sum;
-		if (fn === 'avg') return numbers.length ? sum / numbers.length : 0;
-		return 0;
+	// ─── Query vs Paging ───────────────────────────────────
+	//
+	// Two separate concerns, deliberately kept apart. _queryLocal answers "which
+	// records match, in what order" over the records this store actually holds.
+	// _positionalPage answers "which record sits at logical row N" using the
+	// server's ordering held in _windowIndex. A windowed store needs both; it must
+	// not let the second stand in for the first.
+
+	// Walks in primary-key order collecting matches and stops the moment the
+	// requested slice is full, so the cost tracks the viewport instead of the store
+	// (31ms vs 117ms for a 200-row slice out of 10k records).
+	//
+	// Legal only when the cursor's order already IS the output order, otherwise a
+	// match past the cut could belong ahead of one inside it — so an active sort
+	// disqualifies it. An encrypted store disqualifies it too: decryption is async
+	// and an await inside the cursor callback lets the transaction close.
+	//
+	// When a full pass is unavoidable the getAll path is measurably cheaper than a
+	// cursor (117ms vs 232ms over 10k), so that case is not routed here.
+	function _canScanEarly(options) {
+		return !options.sort && !getCryptoKey();
 	}
 
-	function _decorate(self, records) {
-		if (!self.presenters || !self.presenters.computed) return records;
-		const computed = self.presenters.computed;
-		return records.map(record => {
-			const copy = { ...record };
-			for (const [fieldName, fn] of Object.entries(computed)) {
-				try {
-					copy[fieldName] = fn(record);
-				} catch (err) {
-					console.error(`[ln-data-store] Decorator computed field failed for ${fieldName}`, err);
-				}
-			}
-			return copy;
+	function _scanLocal(self, options, need) {
+		const keys = _filterKeys(options.filters);
+		const tokens = options.search ? _tokenize(options.search) : [];
+		const searchFields = self._searchFields;
+		const useSearch = tokens.length > 0 && searchFields && searchFields.length > 0;
+
+		return _tx(self._name, 'readonly').then(store => {
+			if (!store) return [];
+			return new Promise((resolve, reject) => {
+				const found = [];
+				const request = store.openCursor();
+				request.onsuccess = () => {
+					const cursor = request.result;
+					if (!cursor || found.length >= need) {
+						resolve(found);
+						return;
+					}
+					const record = cursor.value;
+					const passes = (!keys.length || _matchesFilters(record, keys, options.filters))
+						&& (!useSearch || _matchesTokens(record, tokens, searchFields));
+					if (passes) found.push(record);
+					cursor.continue();
+				};
+				request.onerror = () => reject(request.error);
+			});
 		});
 	}
 
-	// ─── Public CRUD & Sync APIs ───────────────────────────
+	function _queryLocal(self, records, options) {
+		return queryRecords(records, options, self._searchFields, _collator);
+	}
 
-	_component.prototype.getAll = function (options = {}) {
-		const self = this;
-		return _getAllRecords(self._name).then(records => {
-			const total = records.length;
+	function _positionalPage(self, offset, limit) {
+		const ids = [];
+		for (let i = offset; i < offset + limit; i++) {
+			const id = self._windowIndex.getId(i);
+			ids.push(id);
+		}
 
-			if (options.filters) records = _filter(records, options.filters);
-			if (options.search) records = _search(records, options.search, self._searchFields);
+		const uniqueResolvedIds = Array.from(new Set(ids.filter(id => id !== undefined)));
 
-			const filtered = records.length;
+		return _getMultipleRecords(self._name, uniqueResolvedIds).then(records => {
+			const recordMap = new Map();
+			for (let i = 0; i < records.length; i++) {
+				const rec = records[i];
+				if (rec) {
+					recordMap.set(String(rec.id), rec);
+				}
+			}
+			const data = [];
+			for (let i = 0; i < ids.length; i++) {
+				const id = ids[i];
+				if (id === undefined) {
+					data.push(null);
+				} else {
+					const rec = recordMap.get(String(id));
+					data.push(rec || null);
+				}
+			}
+			return {
+				data: _decorate(self, data),
+				total: self._windowIndex.grandTotal,
+				filtered: self._windowIndex.logicalTotal,
+				offset: offset,
+				queryGen: self._windowIndex.queryGen
+			};
+		});
+	}
 
-			if (options.sort) records = _sort(records, options.sort);
+	_component.prototype.getAll = function (options = {}) {
+		const self = this;
+		if (self._windowIndex) {
+			const offset = options.offset || 0;
+			const limit = options.limit || 200;
+			self._windowIndex.ensure(offset, offset + limit, options);
+
+			// The index holds no ordering for this query — it was reset the moment
+			// the query changed. Until the server's first page lands the positions
+			// are ours to assign, so the query is answered from the records already
+			// held and flagged provisional; the server's answer supersedes it at the
+			// next generation. Once the index HAS loaded its ordering is authoritative
+			// and a page still missing stays a placeholder — splicing local records
+			// into server positions would put the wrong record on the row.
+			// Told to leave queries to the server: report the window as unresolved and
+			// let the view hold the previous generation until the server answers. The
+			// positional page below stays available either way — those rows are the
+			// server's own answer, only materialised from cache.
+			if (!self._windowIndex.hasLoaded && !self.noLocalQuery) {
+				const need = offset + limit;
+				// Rows only, never totals — see window-cache.ingest. Nothing to show
+				// (empty store, or nothing matched locally) is not an answer either:
+				// the positional page reports the window as unresolved and the view
+				// keeps the previous generation until the server settles it.
+				const provisional = records => records.length
+					? {
+						data: _decorate(self, records),
+						offset: offset,
+						queryGen: self._windowIndex.queryGen,
+						provisional: true
+					}
+					: _positionalPage(self, offset, limit);
 
-			if (options.offset || options.limit) {
-				const offset = options.offset || 0;
-				const limit = options.limit || records.length;
-				records = records.slice(offset, offset + limit);
+				if (_canScanEarly(options)) {
+					return _scanLocal(self, options, need).then(matches =>
+						provisional(matches.slice(offset, need)));
+				}
+				return _getAllRecords(self._name).then(records =>
+					provisional(_queryLocal(self, records, options).records));
 			}
 
+			return _positionalPage(self, offset, limit);
+		}
+
+		return _getAllRecords(self._name).then(records => {
+			const r = _queryLocal(self, records, options);
 			return {
-				data: _decorate(self, records),
-				total,
-				filtered
+				data: _decorate(self, r.records),
+				total: r.total,
+				filtered: r.filtered
 			};
 		});
 	};
@@ -541,9 +769,12 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 	};
 
 	_component.prototype.count = function (filters) {
-		return filters
-			? _getAllRecords(this._name).then(records => _filter(records, filters).length)
-			: _countRecords(this._name);
+		const hasFilters = filters && Object.keys(filters).length > 0;
+		if (!hasFilters) {
+			if (this.totalCount != null) return Promise.resolve(this.totalCount);
+			return _countRecords(this._name);
+		}
+		return _getAllRecords(this._name).then(records => filterRecords(records, filters).length);
 	};
 
 	_component.prototype.aggregate = function (field, fn) {
@@ -559,12 +790,25 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 	_component.prototype.applySync = function (upsertedRecords, deletedIds, syncedAt, meta) {
 		meta = meta || {};
 		const self = this;
+		if (self._windowIndex && meta.queryGen != null && meta.queryGen !== self._windowIndex.queryGen) {
+			return Promise.resolve();
+		}
+
+		const hasChanges = upsertedRecords.length > 0 || deletedIds.length > 0;
 
 		let chain = Promise.resolve();
 		if (upsertedRecords.length > 0) chain = chain.then(() => _putBulk(self._name, upsertedRecords));
 		if (deletedIds.length > 0) chain = chain.then(() => _deleteBulk(self._name, deletedIds));
 
-		return chain.then(() => _countRecords(self._name)).then(count => {
+		return chain.then(() => {
+			if (self._windowIndex && (meta.offset != null || meta.total != null)) {
+				const offset = meta.offset != null ? meta.offset : 0;
+				const ids = upsertedRecords.map(r => r.id);
+				// Residency is the index: what the window pushed out stops being held.
+				const evicted = self._windowIndex.ingest(offset, ids, meta.total, meta.filtered, meta.queryGen);
+				if (evicted && evicted.length) return _deleteBulk(self._name, evicted);
+			}
+		}).then(() => _countRecords(self._name)).then(count => {
 			self.totalCount = meta.total !== undefined ? meta.total : count;
 			self.hasCache = true;
 			return _setMeta(self._name, {
@@ -576,6 +820,7 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 		}).then(() => {
 			const isInitialLoad = !self.isLoaded;
 			self.isLoaded = true;
+			self.canServe = true;
 			self.isSyncing = false;
 			self.lastSyncedAt = syncedAt;
 
@@ -608,8 +853,10 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 
 		return chain.then(() => _countRecords(self._name)).then(count => {
 			self.totalCount = meta.total !== undefined ? meta.total : count;
-			// record_count/has_cache stay untouched — a page fetch is not an
+			// record_count/has_cache/isLoaded stay untouched — a page fetch is not an
 			// authoritative cache; it would corrupt _isStale/storeInitialized sync gating.
+			// It does leave records behind, so the store can serve reads from here on.
+			if (upsertedRecords.length > 0) self.canServe = true;
 			return _decorate(self, upsertedRecords);
 		}).catch(err => {
 			console.error('[ln-data-store] applyQuery failed:', err);
@@ -641,17 +888,27 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 	};
 
 	_component.prototype.destroy = function () {
+		if (this._windowIndex) {
+			this._windowIndex.clear();
+			this._windowIndex = null;
+			this.windowed = false;
+		}
 		if (this._handlers) {
 			for (const [event, fn] of Object.entries(this._handlers)) {
 				this.dom.removeEventListener(`ln-data-store:request-${event}`, fn);
 			}
 			this._handlers = null;
 		}
+		if (this._queryHandlers) {
+			for (const [event, fn] of Object.entries(this._queryHandlers)) {
+				this.dom.removeEventListener(event, fn);
+			}
+			this._queryHandlers = null;
+		}
 
 		delete _stores[this._name];
 
 		delete this.dom[DOM_ATTRIBUTE];
-		dispatch(this.dom, 'ln-data-store:destroyed', { store: this._name });
 	};
 
 	// ─── clearAll (global) ─────────────────────────────────
@@ -669,6 +926,7 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 		}).then(() => {
 			Object.values(_stores).forEach(inst => {
 				inst.isLoaded = false;
+				inst.canServe = false;
 				inst.isInitialized = false;
 				inst.initializationError = null;
 				inst.hasCache = false;
@@ -679,9 +937,53 @@ import { registerComponent, dispatch, setCryptoKey, getCryptoKey, encryptData, d
 		});
 	}
 
+	function _emitQueryChanged(self) {
+		if (self._windowIndex) {
+			self._windowIndex.reset();
+		}
+		dispatch(self.dom, 'ln-data-store:query-changed', {
+			store: self._name,
+			query: {
+				filters: Object.assign({}, self.query.filters),
+				search: self.query.search,
+				sort: self.query.sort ? Object.assign({}, self.query.sort) : null
+			}
+		});
+	}
+
 	// ─── Registration ──────────────────────────────────────
 
-	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _component, 'ln-data-store');
+	const FROZEN_ATTR = 'data-ln-data-store-frozen';
+
+	// The IndexedDB schema and the store's registered name are fixed at open
+	// time: createIndex is only legal inside a versionchange transaction
+	// (see onupgradeneeded, :85-94). A post-init edit is recorded on the host
+	// for the dev stylesheet to surface; nothing is applied.
+	function _markFrozen(el, attrName) {
+		el.setAttribute(FROZEN_ATTR, attrName);
+	}
+
+	// Shrinking the window drops positions; the records behind them stop being
+	// held, exactly as on ingest (:757-758), so they leave IndexedDB too.
+	function _applyWindowSize(el) {
+		const inst = el[DOM_ATTRIBUTE];
+		if (!inst._windowIndex) return;
+		const evicted = inst._windowIndex.configure({ windowSize: inst._windowSize });
+		if (evicted.length) {
+			_deleteBulk(inst._name, evicted).catch(err => {
+				console.error('[ln-data-store] window shrink eviction failed:', err);
+			});
+		}
+	}
+
+	function _applyWindowPageSize(el) {
+		const inst = el[DOM_ATTRIBUTE];
+		if (inst._windowIndex) inst._windowIndex.configure({ pageSize: inst._windowPageSize });
+	}
+
+	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _component, 'ln-data-store', {
+		attributes: ATTRIBUTES
+	});
 
 	window[DOM_ATTRIBUTE].clearAll = _clearAll;
 	window[DOM_ATTRIBUTE].init = window[DOM_ATTRIBUTE];