npm - @3sln/trove - Versions diffs - 0.0.17 → 0.0.19 - Mend

@3sln/trove 0.0.17 → 0.0.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/package.json +1 -1
package/packages/core/src/plugins/runtime.js +61 -5
package/packages/core/src/sidecar/document.js +60 -2
package/packages/core/src/sidecar/index.js +28 -1
package/packages/plugin-sdk/src/browser.js +257 -26
package/packages/plugin-sdk/src/protocol.js +9 -0
package/packages/server/src/routes.js +74 -0
package/packages/web/dist/assets/main-axerf2vw.js +742 -0
package/packages/web/dist/assets/{main-wpfmmbfd.js.map → main-axerf2vw.js.map} +12 -11
package/packages/web/dist/index.html +1 -1
package/packages/web/dist/sw.js +33 -3
package/packages/web/src/bl/fileType.js +8 -0
package/packages/web/src/bl/launcher.js +15 -0
package/packages/web/src/platform/index.js +8 -0
package/packages/web/src/platform/itemData.js +161 -0
package/packages/web/src/platform/navigation.js +16 -2
package/packages/web/src/platform/pluginRpc.js +69 -1
package/packages/web/src/ui/components/launcher.js +1 -1
package/packages/web/src/ui/components/views/index.js +14 -1
package/packages/web/dist/assets/main-wpfmmbfd.js +0 -511

package/packages/web/dist/index.html CHANGED Viewed

@@ -17,6 +17,6 @@
   </head>
   <body>
     <div class="workbench"></div>
-    <script type="module" src="/assets/main-wpfmmbfd.js"></script>
+    <script type="module" src="/assets/main-axerf2vw.js"></script>
   </body>
 </html>

package/packages/web/dist/sw.js CHANGED Viewed

@@ -18,30 +18,60 @@
 // API and FILES deliberately do NOT rotate. API is data, not code, and FILES holds the
 // bytes of files the user pinned for offline use — naming it per build would throw away
 // someone's offline library every time the app was redeployed.
-const SHELL = 'trove-shell-5c503618bc';
+const SHELL = 'trove-shell-7c8b99c0d0';
 const API = 'trove-api-v1';
 const FILES = 'trove-files-v1';
 const KEEP = new Set([SHELL, API, FILES]);
 self.addEventListener('install', (e) => {
-  e.waitUntil(caches.open(SHELL).then((c) => c.addAll(['/', '/index.html', '/icon.svg']).catch(() => {})).then(() => self.skipWaiting()));
+  // Nothing is precached in dev — see the fetch handler. Precaching the shell there is
+  // precisely how a stale build survives a reload.
+  e.waitUntil((isDev
+    ? Promise.resolve()
+    : caches.open(SHELL).then((c) => c.addAll(['/', '/index.html', '/icon.svg']).catch(() => {}))
+  ).then(() => self.skipWaiting()));
 });
 self.addEventListener('activate', (e) => {
   e.waitUntil(
     (async () => {
       const names = await caches.keys();
-      await Promise.all(names.filter((n) => !KEEP.has(n)).map((n) => caches.delete(n)));
+      // In dev, the shell and API caches are not kept at all — including any left behind
+      // by a worker installed before this rule existed, which is the case that otherwise
+      // keeps serving yesterday's HTML until someone clears storage by hand.
+      const keep = isDev ? new Set([FILES]) : KEEP;
+      await Promise.all(names.filter((n) => !keep.has(n)).map((n) => caches.delete(n)));
       await self.clients.claim();
     })(),
   );
 });
+/**
+ * A local development origin, where caching CODE is a liability rather than a feature.
+ *
+ * The shell and the plugin packages are cached by CONTENT, and in production that is
+ * exactly right: assets are fingerprinted, a deploy mints a new shell name, and the old
+ * one is swept. In `wrangler dev` the loop is rebuild-and-reload, many times a minute, and
+ * a cached shell keeps serving the previous build's HTML — which points at the previous
+ * build's bundle. The symptom is the worst kind: a fix that plainly does not take, with no
+ * error anywhere, because the page you are looking at is not the page you just built.
+ *
+ * That cost hours during the audiobook work. So on localhost the worker gets out of the
+ * way for everything except FILE bytes — the offline store is the feature under test some
+ * of the time, and it is keyed by node id and etag rather than by build.
+ */
+const DEV_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '0.0.0.0']);
+const isDev = DEV_HOSTS.has(self.location.hostname);
 self.addEventListener('fetch', (event) => {
   const req = event.request;
   const url = new URL(req.url);
   if (url.origin !== self.location.origin || req.method !== 'GET') return; // only same-origin GETs
+  // Dev: code and API responses go straight to the network, uncached. Pinned file bytes
+  // still go through, because that machinery is worth exercising locally.
+  if (isDev && url.pathname !== '/api/items/download') return;
   if (url.pathname === '/api/items/download') {
     event.respondWith(pinnedFirst(req));
     return;

package/packages/web/src/bl/fileType.js CHANGED Viewed

@@ -76,6 +76,14 @@ export const THUMBNAIL_KEY = 'thumbnail';
  * @returns {{range?: {start: number, end: number}, src?: string, contentType?: string}|null}
  */
 export function thumbnailOf(node) {
+  // ALREADY RESOLVED, which is how a recents entry carries one. Recents are a snapshot in
+  // localStorage rather than a reference — nothing re-reads the node — so the descriptor
+  // is stored on the entry itself and this is where it comes back in. Same shape, so a
+  // view cannot tell the two apart, which is the point.
+  const stored = node?.thumbnail;
+  if (typeof stored?.src === 'string' && stored.src) return stored;
+  if (Number.isFinite(stored?.range?.start) && Number.isFinite(stored?.range?.end)) return stored;
   const contributions = node?.contributions;
   if (!contributions) return null;
   for (const contribution of Object.values(contributions)) {

package/packages/web/src/bl/launcher.js CHANGED Viewed

@@ -28,6 +28,21 @@ export function launcherMode(query) {
   return q.startsWith('!') ? 'command' : q.includes('#') ? 'filter' : 'search';
 }
+/**
+ * Does this mode put FILES on screen?
+ *
+ * Asked because a view is a way of drawing files, so anything that decides "can the user
+ * switch views" has to know whether files are what is being shown. `!` lists commands —
+ * there is no second way to draw a command, and offering a grid/list toggle over them
+ * says the results are something they are not.
+ *
+ * Expressed as a question about the mode rather than a check for `'command'` at the call
+ * site, so a future mode that lists something else is handled here, once.
+ */
+export function modeShowsItems(mode) {
+  return mode !== 'command';
+}
 /**
  * Everything you can do to a file, as descriptions.
  *

package/packages/web/src/platform/index.js CHANGED Viewed

@@ -20,6 +20,7 @@ import { ViewportService } from './viewport.js';
 import { SpatialNavigationService } from './spatialNav.js';
 import { VoiceSearchService } from './voiceSearch.js';
 import { MediaUrlService } from './mediaUrls.js';
+import { ItemDataService } from './itemData.js';
 import { FileChunks } from './fileChunks.js';
 /**
@@ -81,6 +82,13 @@ export function createPlatform({ baseUrl = '' } = {}) {
   // for, or the network keeping nothing. See fileChunks.js — the retention rule is the
   // whole point of it having a name of its own.
   platform.fileChunks = new FileChunks({ api: platform.api, mediaUrls: platform.mediaUrls });
+  // Per-plugin, per-item state — a listening position, a last page. Local first, merged
+  // with the server's sidecar when there is one. See itemData.js for why it is neither a
+  // contribution nor a setting.
+  platform.itemData = new ItemDataService({
+    api: platform.api,
+    actor: () => platform.identity?.get?.()?.principal?.id || 'local',
+  });
   platform.plugins = new PluginHost(platform);
   // Commands consult the plugin host to hide/disable plugin commands that aren't
   // available right now (offline, or the plugin isn't responding).

package/packages/web/src/platform/itemData.js ADDED Viewed

@@ -0,0 +1,161 @@
+// A plugin's key/value data for an item, local first and merged with the server.
+//
+// The plugin sees one interface and is told nothing about where the bytes are — see the
+// SDK's `files.data(id)`. That is the point: a viewer saving a listening position should
+// not have to know whether the drive is reachable, and should not lose the position when
+// it is not.
+//
+// SHAPE. Every write lands in a local map immediately, stamped, and is queued. The queue
+// flushes to `/api/items/:id/data` when it can; the server merges into the item's sidecar,
+// which is a CRDT, and answers with the merged view. A read is the local map merged over
+// whatever the server last said.
+//
+// The merge rule is last-write-wins on a wall-clock stamp, with the actor breaking ties —
+// the same rule the sidecar uses, so both ends agree without either being authoritative.
+// Wall clock rather than the sidecar's Lamport counter because these writes originate on
+// devices that have never spoken to each other: two phones, one of them offline for a day.
+// A Lamport clock cannot order those; a timestamp can, imperfectly and good enough for
+// "where was I in this book".
+//
+// PERSISTENCE is localStorage, not IndexedDB. This is a handful of small values per item
+// — a position, a rate, a bookmark — and localStorage is synchronous, which means a write
+// survives the tab being closed a millisecond later. An async store would not.
+const KEY = 'trove.itemData';
+const FLUSH_MS = 2000;
+const MAX_ENTRIES = 5000;
+export class ItemDataService {
+  /**
+   * @param {object} deps
+   * @param {import('./api.js').Api} deps.api
+   * @param {() => string} [deps.actor] who is writing, for tie-breaks
+   */
+  constructor({ api, actor = () => 'local' } = {}) {
+    this.api = api;
+    this.actor = actor;
+    this.local = load();          // scope -> nodeId -> key -> { value, present, at, actor }
+    this.pending = new Set();     // `${scope}\0${nodeId}` awaiting a flush
+    this.server = new Map();      // `${scope}\0${nodeId}` -> plain object last seen
+    this.timer = null;
+  }
+  /**
+   * Everything this plugin knows about this item.
+   *
+   * Local over server, because local includes writes the server has not seen yet. A
+   * server fetch is kicked off but not waited on: a viewer opening a book should draw
+   * immediately from what this device already knows, and correct itself a moment later
+   * if another device got further.
+   */
+  async get(scope, nodeId) {
+    const merged = { ...(this.server.get(k(scope, nodeId)) || {}) };
+    for (const [key, cell] of Object.entries(this.local[scope]?.[nodeId] || {})) {
+      if (cell.present) merged[key] = cell.value;
+      else delete merged[key];
+    }
+    this.#refresh(scope, nodeId);
+    return merged;
+  }
+  /** Write now, locally; tell the server when there is one. */
+  async set(scope, nodeId, key, value) {
+    if (!key) return { ok: false };
+    this.#put(scope, nodeId, key, { value, present: true });
+    return { ok: true };
+  }
+  async remove(scope, nodeId, key) {
+    if (!key) return { ok: false };
+    // A tombstone, not a delete: the server may still hold the old value, and an absence
+    // has to be a fact with a stamp or the merge will bring it back.
+    this.#put(scope, nodeId, key, { value: null, present: false });
+    return { ok: true };
+  }
+  #put(scope, nodeId, key, cell) {
+    this.local[scope] ||= {};
+    this.local[scope][nodeId] ||= {};
+    this.local[scope][nodeId][key] = { ...cell, at: Date.now(), actor: this.actor() };
+    save(this.local);
+    this.pending.add(k(scope, nodeId));
+    this.#schedule();
+  }
+  #schedule() {
+    if (this.timer) return;
+    // Coalesced: a scrubbing listener writes a position several times a second, and one
+    // request per write would be a request per frame.
+    this.timer = setTimeout(() => { this.timer = null; this.flush().catch(() => {}); }, FLUSH_MS);
+  }
+  /**
+   * Push what is queued and take back what the server merged.
+   *
+   * A failure keeps the item queued — that is the whole reason writes are local first, and
+   * dropping the queue on a flaky network would defeat it. Nothing is retried immediately;
+   * the next write, or the next flush, carries it.
+   */
+  async flush() {
+    for (const id of [...this.pending]) {
+      const [scope, nodeId] = id.split('\0');
+      const cells = this.local[scope]?.[nodeId];
+      if (!cells) { this.pending.delete(id); continue; }
+      const entries = Object.entries(cells).map(([key, c]) => ({ key, value: c.value, remove: !c.present }));
+      try {
+        const res = await this.api.request('POST', `/api/items/${encodeURIComponent(nodeId)}/data`, {
+          query: { scope }, body: { entries },
+        });
+        this.pending.delete(id);
+        this.server.set(id, res?.data || {});
+        // The local copy has served its purpose once the server has it: keeping it would
+        // make a stale local value outlive a newer one written elsewhere.
+        delete this.local[scope][nodeId];
+        save(this.local);
+      } catch {
+        // Left queued deliberately. See above.
+      }
+    }
+  }
+  /** Ask the server what it has, without blocking the caller that wanted a value. */
+  #refresh(scope, nodeId) {
+    const id = k(scope, nodeId);
+    if (this.inflight?.has(id)) return;
+    (this.inflight ||= new Set()).add(id);
+    this.api.request('GET', `/api/items/${encodeURIComponent(nodeId)}/data`, { query: { scope } })
+      .then((res) => { this.server.set(id, res?.data || {}); })
+      .catch(() => {})
+      .finally(() => this.inflight.delete(id));
+  }
+}
+const k = (scope, nodeId) => `${scope}\0${nodeId}`;
+function load() {
+  try {
+    const raw = JSON.parse(localStorage.getItem(KEY)) || {};
+    return raw && typeof raw === 'object' ? raw : {};
+  } catch { return {}; }
+}
+function save(local) {
+  try {
+    // Bounded, because this is localStorage and a plugin writing per-item state across a
+    // large drive would otherwise fill it and start throwing on every write — including
+    // the writes of every other feature that shares the quota. Oldest stamps go first.
+    const flat = [];
+    for (const [scope, nodes] of Object.entries(local)) {
+      for (const [nodeId, cells] of Object.entries(nodes)) {
+        for (const [key, cell] of Object.entries(cells)) flat.push({ scope, nodeId, key, cell });
+      }
+    }
+    if (flat.length > MAX_ENTRIES) {
+      flat.sort((a, b) => (a.cell.at || 0) - (b.cell.at || 0));
+      for (const { scope, nodeId, key } of flat.slice(0, flat.length - MAX_ENTRIES)) {
+        delete local[scope][nodeId][key];
+      }
+    }
+    localStorage.setItem(KEY, JSON.stringify(local));
+  } catch { /* private mode, or full: the in-memory copy still works for this session */ }
+}

package/packages/web/src/platform/navigation.js CHANGED Viewed

@@ -6,6 +6,7 @@
 // activity to 'home' and closing the modal search when a file opens).
 import { cell } from '../runtime.js';
+import { thumbnailOf } from '../bl/fileType.js';
 const RECENTS_KEY = 'trove.recents';
 const RECENTS_MAX = 12;
@@ -126,7 +127,7 @@ export class NavigationService {
    */
   updateTabNode(node) {
     const recents = this.#state.recents.map((r) => (r.id === node.id
-      ? { ...r, name: node.name, contentType: node.contentType || r.contentType }
+      ? { ...r, name: node.name, contentType: node.contentType || r.contentType, ...(thumbnailOf(node) ? { thumbnail: thumbnailOf(node) } : {}) }
       : r));
     if (recents.some((r, i) => r !== this.#state.recents[i])) {
       this.#set({ recents });
@@ -160,7 +161,20 @@ export class NavigationService {
   #pushRecent(node) {
     if (!node) return;
-    const entry = { id: node.id, name: node.name, contentType: node.contentType || '', collectionId: node.collectionId };
+    // The THUMBNAIL rides along, and it has to, because a recent entry is a snapshot
+    // rather than a reference: nothing later re-reads the node, so a tile drawn from
+    // this object sees whatever is stored here and nothing else. Without it a recently
+    // opened book showed a generic icon while the very same file two rows below showed
+    // its cover — the one difference being which group drew it.
+    //
+    // Only the descriptor, not the image. It is a range into the file (~80 bytes), so a
+    // dozen of them is under a kilobyte of localStorage; storing the whole contribution
+    // would put four kilobytes per book in there for no gain.
+    const thumbnail = thumbnailOf(node);
+    const entry = {
+      id: node.id, name: node.name, contentType: node.contentType || '', collectionId: node.collectionId,
+      ...(thumbnail ? { thumbnail } : {}),
+    };
     const recents = [entry, ...this.#state.recents.filter((r) => r.id !== node.id)].slice(0, RECENTS_MAX);
     this.#set({ recents });
     saveRecents(recents);

package/packages/web/src/platform/pluginRpc.js CHANGED Viewed

@@ -165,6 +165,61 @@ export class PluginRpcRouter {
         return { bytes: r.bytes.buffer, etag: r.etag, total: r.total };
       }
+      // Is the whole file already HERE, in this browser?
+      //
+      // The question a viewer has to ask before deciding what to draw, and it is cheap on
+      // purpose: `status` reads bookkeeping, not bytes, so a plugin can ask on every open
+      // without pulling a hundred megabytes to find out the answer is no.
+      case 'files:hasLocal': {
+        cap('files');
+        const st = this.platform.fileChunks.status(params.id);
+        return { local: !!st.done, loaded: st.loaded, total: st.total, ratio: st.ratio, filling: st.filling };
+      }
+      // The whole file as a real Blob, or null.
+      //
+      // This exists because of the frame's CSP: `media-src blob: data:` and
+      // `connect-src 'none'`, deliberately, so a viewer CANNOT load a media URL — see
+      // pluginFrames.js. A Blob it can. So a downloaded book plays by handing the frame
+      // the bytes it already paid for, rather than by punching a hole in the sandbox.
+      //
+      // Null rather than a partial when the file is incomplete: half an MP4 is not a
+      // shorter MP4, and a viewer that got one would fail in a way that looks like a
+      // decoder bug instead of a missing download.
+      case 'files:localBlob': {
+        cap('files');
+        const st = this.platform.fileChunks.status(params.id);
+        if (!st.done || !st.total) return { blob: null };
+        const r = await this.platform.fileChunks.read(params.id, { start: 0, end: st.total });
+        // A Blob crosses by structured clone WITHOUT copying its bytes — the handle is
+        // refcounted — which is why this is a Blob and not the ArrayBuffer `files:bytes`
+        // transfers. Transferring would detach the buffer the offline store is holding.
+        const node = await this.platform.api.stat(params.id).catch(() => null);
+        return { blob: new Blob([r.bytes], { type: node?.node?.contentType || 'application/octet-stream' }) };
+      }
+      // A plugin's own key/value data for an item — see sidecar/document.js.
+      //
+      // The scope is derived from the AUTHENTICATED plugin, never from the params: a
+      // frame asking for someone else's namespace gets its own. That is the same rule
+      // `files:index` follows for contributions, and the reason "scoped" is a boundary
+      // rather than a naming convention.
+      case 'items:data:get': {
+        cap('files');
+        return this.platform.itemData.get(pid, params.id);
+      }
+      case 'items:data:set': {
+        cap('files');
+        // Written locally FIRST and flushed later, so a viewer that saves a position on a
+        // train keeps it, and the merge happens when there is a network again. See
+        // platform/itemData.js.
+        return this.platform.itemData.set(pid, params.id, params.key, params.value);
+      }
+      case 'items:data:remove': {
+        cap('files');
+        return this.platform.itemData.remove(pid, params.id, params.key);
+      }
       // Keeping a file offline, which is a DIFFERENT act from reading it — see
       // fileChunks.js. Until `start` is called, ranging over a file stores nothing.
       case 'files:offline:start': return cap('files'), this.platform.fileChunks.start(params.id);
@@ -308,7 +363,20 @@ export class PluginRpcRouter {
   /** blob:/data: carry their own bytes; anything else must be a declared endpoint. */
   #artworkAllowed(record, src) {
     if (!src) return false;
-    if (/^(blob:|data:image\/)/i.test(src)) return true;
+    if (/^data:image\//i.test(src)) return true;
+    // A `blob:` URL from a plugin frame is ALWAYS unusable here, and accepting one was
+    // worse than refusing it: the frame runs on an opaque origin, so its object URLs are
+    // `blob:null/…`, and this page cannot load another origin's blob. The browser says
+    // "Not allowed to load local resource" against the HOST document — a message that
+    // names neither the plugin nor the artwork, for a lock-screen image that simply never
+    // appeared.
+    //
+    // There is no version of this that works: a frame cannot mint a URL in this origin.
+    // Artwork has to arrive as bytes, which `data:image/…` above is.
+    if (/^blob:/i.test(src)) {
+      console.warn(`[trove] ${record.id}: media artwork must be a data: URL — a blob: from a sandboxed frame is opaque-origin and cannot be loaded here`);
+      return false;
+    }
     return isAllowedUrl(networkEndpoints(record.manifest), src);
   }

package/packages/web/src/ui/components/launcher.js CHANGED Viewed

@@ -153,7 +153,7 @@ export default function launcher(state, ui, opts = {}) {
         : null,
       // Which way to look at the drive. Not in the modal search, where the answer is
       // always "the one thing I am about to press Enter on".
-      modal ? null : viewSwitcher(state.views, view, ui),
+      modal ? null : viewSwitcher(state.views, view, ui, { mode }),
     ),
     showResolved ? resolvedBar(resolved) : null,
     // The results belong to the active view — see ui/components/views. The launcher says

package/packages/web/src/ui/components/views/index.js CHANGED Viewed

@@ -22,6 +22,7 @@ import { dd } from '../../../runtime.js';
 import { icon } from '../../icon.js';
 import { SetSettingAction } from '../../../bl/actions.js';
 import { SETTING } from '../../../bl/views.js';
+import { modeShowsItems } from '../../../bl/launcher.js';
 import { listView } from './list.js';
 import { gridView, gridMove } from './grid.js';
@@ -49,7 +50,19 @@ export function registerBuiltinViews(platform) {
 /** The switcher, shown only when there is more than one way to look at this. */
-export function viewSwitcher(slice, current, ui) {
+export function viewSwitcher(slice, current, ui, { mode } = {}) {
+  // Two conditions, and the control is furniture without both.
+  //
+  //   1. The results are FILES. `!` lists commands, and a grid/list toggle over a list of
+  //      commands is meaningless — see `modeShowsItems`. This is the one that was missing.
+  //   2. There is more than one view.
+  //
+  // Not, note, "more than one view MATCHES these results". A view's `match` is a
+  // PREFERENCE, not a restriction — the grid declares `image/*` to be offered first where
+  // the results are pictures, and is available everywhere regardless. Filtering by it hid
+  // the grid on a drive of audiobooks, which is the opposite of the point. If a view ever
+  // needs to say "I cannot draw this", that wants its own field rather than a reused one.
+  if (mode !== undefined && !modeShowsItems(mode)) return null;
   const views = slice?.views || [];
   if (views.length < 2) return null;
   return div({ className: 'view-switch' }, ...views.map((v) =>