Omniscio

Shares view (master/detail sidebar + in-app webview viewer for shared links) (part 2)

Shares is inside the System group in the sidebar — expand System and click Shares. It is registered in INTEGRATIONREGISTRY as a virtual project with sentinel SHARESPROJECTID (from src/shared/virtual-project-ids.ts). UI registry shape.

On this page

What it is

This is part 2 of the Shares view (master/detail sidebar + in-app webview viewer for shared links) page. It carries the next stretch of the material on that page, moved here because a single page is capped at 40,000 characters.

Where to find it

Reach this part through Shares view (master/detail sidebar + in-app webview viewer for shared links) — it lists every part and explains where the feature lives in the product. Everything below is reached from the same place.

How it behaves

Everything below is the behaviour, detail and edge cases that belong to this stretch of the Shares view (master/detail sidebar + in-app webview viewer for shared links) page.

How it works

  • Installed Plugins entry. Registered in INTEGRATION_REGISTRY (listed on the Installed Plugins page; its In side nav switch adds it to the side nav) as a virtual project with sentinel SHARES_PROJECT_ID (from src/shared/virtual-project-ids.ts).
  • UI registry shape. The Shares entry in src/renderer/src/integrations/ui-registry.ts is a two-component integration: panelComponent: lazy(() => import('../features/shares/SharesDetailPane')) + sidebarComponent: lazy(() => import('../features/shares/SharesSidebar')). Both components are lazy-loaded — the integration-ui-registry-lazy lint test enforces no static imports from the entry chunk. There is no panelOwnsLayout flag on Shares; the standard RoutedSubSidebar mounts SharesSidebar in the normal sidebar slot. Mirrors the Cron Jobs two-pane shape.
  • Activation. All navigation that wants to land on this view MUST route through activateVirtualProject(SHARES_PROJECT_ID, source) from src/renderer/src/lib/activate-virtual-project.ts — that helper resolves the sentinel to the project-row UUID before calling setActiveProject (passing the sentinel directly to setActiveProject silently no-ops, per the virtual-project activation contract).
  • Share URL interception. When any call to openExternalUrl encounters a URL matching a share host (https://shares.omniscio.com/s/<token> — the brand default — or the legacy https://agentmc-shares.web.app/s/<token>; regex SHARE_URL_RE, built from the shared SHARE_HOSTING_DOMAINS list, in src/renderer/src/lib/platform.ts), the share is opened in-app instead of launching an external browser. The function calls resolveShareUrlToken(token, opts) from the registration-seam module src/renderer/src/lib/share-url-intercept-access.ts, which looks up the token in the local share list. A #comments deep link takes the detail-pane path (select the row, arm the comment scroll, activate the Shares virtual project) and needs the loaded row, so an unsynced token there falls through to the system browser. Otherwise it opens the full-size in-app share popup — a large centered card over a dim, click-to-close backdrop (Escape, Ctrl+W, or the header X close it too — and Escape/Ctrl+W close it even when focus is inside the share's <webview>, forwarded from the main process via the WEBVIEW_GUEST_DISMISS push), dropped below the 50px CustomTitlebar strip (topOffset) so the window's min/maximize/close controls stay un-dimmed and clickable; it mirrors the ImageLightboxShell media-modal pattern and, like the detail pane's fullscreen layer, declares role="dialog" + Escape while deliberately taking no aria-modal/focus-trap of its own on the embedded webview's behalf — via openFloatingShare(token). Any valid share token opens in-app when sharesOpenInApp is on — owned OR a teammate's (shares open in-app everywhere they appear — team chat, AI chat, inbox — not just your own). An OWNED token renders with its full metadata (label, staleness, reload-on-republish); a NON-owned token has no local row, so FloatingShareViewer synthesizes a minimal card whose <webview> src is built from the token via buildShareUrl (src/shared/share-hosting-domains.ts) — the canonical, fixed-domain https://shares.omniscio.com/s/<token>, never the link's raw href. openFloatingShare still fetches the owned list on demand, so an owned-but-unsynced just-published token upgrades to its rich metadata once it lands. When sharesOpenInApp is OFF the resolver returns false and the caller opens the system browser (unchanged); a #comments deep link still needs the loaded row, so an unsynced token there falls through to the browser. Security invariant (build-from-token — this REPLACES the former own-only rule): the viewer's <webview> src is ALWAYS built from the VALIDATED token, so it can only ever load a well-formed Omniscio share page — a malformed token makes buildShareUrl return null and the viewer simply stays closed, and a raw/hostile URL can never be coerced into the privileged viewer. Locked by tests/unit/shared/share-hosting-domains.test.ts (buildShareUrl charset/length + null-on-malformed), tests/unit/features/shares/FloatingShareViewer.test.tsx (a non-owned token opens by building the canonical URL; a malformed token stays closed), and tests/unit/stores/share-store.test.ts (the ambient path opens in-app when the setting is on, browser when off). The app-wide freshness that makes agent-published shares resolve reliably comes from SharesLiveSync (below). A bypass function openExternalUrlForce(url) skips interception entirely — used by the viewer's own "Open in browser" buttons, the right-click "Open in browser" item on an in-app share link in chat (CopyableLink → CopyableLinkMenu; the escape hatch that opens the real share URL in the system browser instead of the in-app popup, shown for a share link that renders in-app — owned or a teammate's — since a plain external link already opens externally on click), and by DeckPublishedDialog (which shows a just-published share URL that would otherwise be recursively intercepted). The registration-seam pattern (mirrors session-nav-store-access.ts) prevents an import cycle: platform.ts is a foundational leaf that ipc.ts imports at module scope, so it cannot statically import share-store.ts (which imports ipc.ts).
  • Share hosting domain (brand + legacy). New share links mint on the brand domain https://shares.omniscio.com (the product-wide default); the original https://agentmc-shares.web.app stays fully served, so every already-sent link keeps resolving — both hostnames point at the SAME Firebase Hosting site, so content is byte-identical and the serveShare Cloud Function needs no per-host logic (the unlock cookie is Path=/s/<token>, host-only — no redeploy required). The two hostnames live in ONE module, src/shared/share-hosting-domains.ts (PRIMARY_SHARE_HOSTING_DOMAIN + LEGACY_SHARE_HOSTING_DOMAIN + the SHARE_HOSTING_DOMAINS allowlist), which the URL generator (firebase-publisher) and every matcher (interception regex, CSP frame-src, framing-header strip, team-chat link classifier, broadcast-embed origin allowlist) import — so a future domain change lands in one place. The per-user firebaseHostingDomain setting still overrides the default. The /t/* relay endpoints are NOT share links and deliberately stay on agentmc-shares.web.app.
  • Deep-link route for shares. omniscio://share/<token> (or agentmc://share/<token>) opens a share in the built-in viewer. Parsed by parseDeepLinkUrl() as { action: 'open-share-in-viewer', token } — a bare token (no sub-action) triggers the viewer route; the existing share/fork/<token> sub-action is unaffected. The renderer's routeDeepLinkAction dispatches to openShareInViewer(token) (wired in useDeepLinkListener to resolveShareUrlToken(token, { openInViewer: true })), which navigates to the Shares panel and opens the share in view mode. If the token is unknown locally, the renderer shows an error toast. Builder: shareViewerDeepLink(token) in src/main/services/deep-link.ts.
  • CSP frame-src. The webview viewer and any remaining iframe usage requires BOTH share hosts in the renderer CSP frame-src (https://shares.omniscio.com + the legacy https://agentmc-shares.web.app) in src/renderer/index.html. Without them, framed content from the share host is blocked. Pinned by tests/unit/lib/shares-iframe-csp.test.ts so a future CSP hardening pass can't drop the directive silently.
  • Response-header override. The Cloud Function correctly serves share shell pages with X-Frame-Options: DENY and CSP frame-ancestors 'none' (anti-clickjacking for external browsers). The Electron main process strips these two framing headers from share-host responses loaded as sub-frames via session.webRequest.onHeadersReceived (src/main/services/share/share-preview-headers.ts, registered in src/main/app/window.ts). Only subFrame resource types on a share page or its /run document are affected — the path test is isFramableSharePath in src/shared/share-hosting-domains.ts, built from the one shared SHARE_REF_INNER, so a 16/64-char token, a 4-80 char short code and a paid custom name all qualify (a hand-written token-only pattern here previously left every short-code share unframable, and it rendered as a blank frame with nothing reported anywhere). Main-frame navigations and all other resource types pass through unmodified. Both the frame-src CSP allowlist AND this header override are required for the webview to load share content.
  • Shares reopen instantly — yours and your teammates'. The viewer keeps a copy on this computer. Your own unprotected shares open from it with nothing downloaded, including the first open: the app writes the copy the moment it publishes the share (the page and its run document, fetched speculatively so it is never counted as a view). Your own video plays from its original file when it is unchanged. Your own copies also follow changes to how the share site serves pages (a new report bar, say): a copy the site has not confirmed in 15 minutes still opens at once, while a count-free background check asks whether it changed — an unchanged page is not downloaded again, a changed one replaces the copy for the next open. Before this, your own copies were frozen at publish time, which is how the old white "Report this page" pill kept showing in the app after the site moved it into a bar (Nov 18, 2026). Someone else's share — and a protected one of yours — opens on its own session (persist:share-viewer, never the in-app browser's), where its page, video and audio / page document are kept too. The share server only marks a share keepable when it has no password, no view limit and no view alerts, and a revoked or expired share is refused outright, which deletes the copy. A copy the server approved in the last 15 minutes (the app re-checks shares in an open Team Chat conversation) opens from disk at once while the real request still goes to the server in the background; an older copy asks first. Re-checks ask "has it changed?" with the app's own header, because Firebase Hosting drops the standard one — so an unchanged share is never downloaded again. A kept video is re-checked against the stored file with a 1-byte request, then plays from disk. A video with no kept copy still plays: the viewer is handed the storage bytes themselves, never the share server's redirect to storage — the app's own protocol.handle('https') covers every request on the viewer's session, so a media element's ranged first request came back as the redirect's own shape (a 2-byte text/plain, no 206) and failed resource selection outright, which is why a share's page rendered perfectly and its video never played. The handler reads the storage URL itself, forwards the element's Range, and returns that answer with its media headers. The in-app proof is tests/e2e/ui/share-popup-video-never-streams.spec.ts: it opens a share through the omniscio://share/<token> deep link in the floating viewer and requires the inner /run frame's video to reach readyState >= 2 after play(). It reads a LIVE share — a dedicated never-expiring share of tests/e2e/fixtures/video/two-second-clip.mp4 — so a 404 on its page means the fixture share is gone (republish the clip with expiresIn: never and update SHARE_REF), not that the app broke; its first fixture, a user's recording, was deleted on the server by Nov 6, 2026 and turned the spec red with best readyState -1. A busy app never stops a share playing. Everything the viewer is handed — the storage stream, your own video file, a kept video, a kept page and its record — is read through the viewer session's own Chromium fetch (its network service and file loader), never Node's file or network calls. Those share one four-thread pool in the main process with everything else the app does, and on Nov 13, 2026 that pool was jammed for hours: each video request waited 10–16 s, the storage fetch timed out, and no video played in the app while the same links played in a browser. Copies are still WRITTEN with Node, in the background. New video shares in the open Team Chat channel and in the inbox are saved in the background (newest three, once per app run) — only videos on free-to-download storage are ever kept. Copies of other people's shares live in share-cache-checked/ (5 GB, 7 days unused).
  • Links inside a share open in your browser. A link a user clicks inside a rendered share's artifact — a sub-frame navigation to an off-origin site — opens in the system browser instead of dying inside the sandboxed <iframe> (a bare in-artifact link previously loaded into the tiny frame and silently failed against the target's X-Frame-Options). The main process wires a will-frame-navigate handler in src/main/webcontents-hardening.ts that externalizes off-origin http(s) navigations originating from a share-owned frame (the artifact itself + the full-bleed about:srcdoc fit-host, decided by the exported isShareOwnedFrame helper) through the validated shell.openExternal path — while a nested off-origin embed the artifact legitimately included (e.g. a YouTube iframe) keeps loading/navigating in place, same-origin sub-resource loads (the shell's own /run frame) pass through untouched, and same-document #anchor links (which never fire will-frame-navigate) are unaffected. That handler covers the common plain link (will-navigate fires for the main frame only, so it never saw the sub-frame click). A target="_blank" link — which is what the report template's source link and the "Made with Omniscio" badge emit — takes a different path: it is a window.open, externalized by setWindowOpenHandler, and Electron refuses a <webview> guest's window.open outright unless the tag carries allowpopups="true". The refusal happens below the app, so until the share viewer opted in (src/renderer/src/features/shares/ShareViewerWebview.tsx) setWindowOpenHandler was never consulted and clicking a _blank link inside a share did nothing at all. Opting in grants no privilege — the handler still returns deny for every popup, so no window opens in-app; it only gets the chance to hand the URL to shell.openExternal. The same shared hardening also benefits the shared-partition Gmail link viewer. Locked by tests/unit/main/webcontents-hardening.test.ts (the externalize path) + tests/unit/features/shares/ShareViewerWebview.test.tsx (the allowpopups opt-in).
  • In-page #anchor nav works inside srcdoc-hosted shares. A separate issue from the off-origin externalization above: a responsive/fixed-width full-bleed artifact renders in an about:srcdoc frame (src/main/services/share/share-artifact-builder.ts / buildFitHost), whose base URL is inherited from the parent /run URL — so the browser resolved a bare #section link to …/run#section, a cross-document navigation that yanked the artifact off screen (blank). The fix injects a tiny click interceptor (SRCDOC_ANCHOR_SCROLL_SCRIPT in src/main/services/share/share-artifact-scripts.ts) into ONLY the two srcdoc hosts that preventDefaults a same-page # click and scrolls in-document instead. A directly-served (/run, non-srcdoc) artifact keeps its own real URL as the base, so its #id links already work and it is deliberately left untouched. Existing shares recover via the viewer's Refresh button; they get the permanent fix on re-publish. Locked by tests/unit/services/srcdoc-anchor-scroll.test.ts (click behavior) + the srcdoc-anchor wiring cases in tests/unit/services/share-artifact-builder-presentation.test.ts.
  • Store. All master + detail state lives in src/renderer/src/stores/share-store.ts. On top of the legacy shares / isCreating / error slices, the store owns selectedShareId, searchQuery, kindFilter ('all' | 'thread' | 'artifact' | 'digest'), collapsedGroups (a Set<'unread' | 'live' | 'archived'> seeded with 'archived' so that section starts collapsed; in-memory only, resets each launch — mirrors the Cron sidebar), and pendingViewMode ('view' | null — set by the share URL resolver when openInViewer is true, consumed by SharesDetailPane during render to open in view mode instead of edit mode, then cleared; resolving it in render rather than in an effect keyed on share.id is what makes the first commit the right one), plus setSearch / setKindFilter / toggleGroupCollapsed. A derived selector useGroupedShares() applies the kind + search filters and partitions the survivors into { unread, live, archived } — any share with unread comments leads in unread (pinned on top, whatever its state), the rest split by active-vs-(revoked-or-expired). fetchShares clears selectedShareId only when the selected row has vanished server-side (so revoke/delete from another window doesn't strand the detail pane); a status change no longer clears it, because the row simply moves into the Archived section. revokeShare, deleteShare, republishShare all do an optimistic local write, then await get().fetchShares().catch(() => {}) in finally so a missed SHARE_UPDATED push doesn't leave the UI desynced. updateShareInPlace(id) re-reads the share's sourcePath and invokes SHARE_PUBLISH_ARTIFACT with updateToken (the share's own token), refetching in finally; it resolves { url, id, updatedInPlace } so the pane stays on the same row on a same-link update and lands on the new row on the relay fallback.
  • Data source. SharesLiveSync (mounted app-wide in GlobalModals) calls fetchShares() (which invokes ipc.invoke(IPC.SHARE_LIST, { includeRevoked: true })) on mount and on every SHARE_UPDATED push, so the store's shares list is hydrated on every view — not just when the Shares panel is open. SharesSidebar calls fetchShares() on mount but has no SHARE_UPDATED listener of its own, so a push is fetched once, by SharesLiveSync. SharesDetailPane reads the currently-selected share out of the store and does NOT subscribe. The handler is src/main/ipc/share-handlers.ts.
  • SHARE_UPDATE IPC. Channel registered in share-handlers.ts next to SHARE_REVOKE / SHARE_DELETE. Schema is shareUpdateSchema in src/shared/ipc-schemas.ts — { id: string, patch: { label?: string, expiresAt?: string | null, liveUpdating?: boolean, viewCap?: number | null, notifyOnView?: boolean, commentsEnabled?: boolean, muteNotifications?: boolean } }. Handler reads the existing row (returns { success: false, error: 'Share not found: ...' } if missing), calls shareQueries.updateShare(id, patch), mirrors the patch to Firestore, emits SHARE_UPDATED with action: 'updated', returns { success: true, data: { share } }. The SHARE_UPDATED push channel includes 'updated' alongside the existing 'created' | 'revoked' | 'deleted' | 'expired' actions. Password protection is a separate channel.
  • SHARE_SET_PROTECTION IPC. Dedicated channel for the password hash/salt handshake so plaintext never round-trips through the patch object. Schema is shareSetProtectionSchema in src/shared/ipc-schemas.ts — { id: string, passwordHash: string(64-hex) | null, passwordSalt: string(32-hex) | null }. Both fields must move together (both set, or both null — partial sets are rejected). Handler updates the SQLite row + Firestore mirror, emits SHARE_UPDATED with action: 'updated', returns { success: true, data: { share } }. passwordHash / passwordSalt are stripped from every IPC response — only the renderer-facing hasPassword: boolean is exposed.
  • Share view poller. src/main/services/share/share-view-poller.ts runs as a periodic task with a fixed 60 s timer and immediate: false (the first run is 60 s after start — no jitter, no separate initial delay) via createPeriodicTask. Each tick asks the relay which shares changed since a persisted cursor, compares view_count / last_viewed_at against the local row, writes the deltas into the local shares row, then fires a desktop notification for each share with notify_on_view = 1 AND mute_notifications = 0 whose count advanced. No per-view event rows are appended — that feed is retired (VIEW_EVENTS_MIRROR_SUPPORTED = false). Any advance resets the cadence to 60 s; after three consecutive idle ticks the relay reads back off exponentially to at most once every 5 minutes, and a view or comment snaps them back to 60 s. The row write commits before the notification fires for crash-safe ordering.
  • Schema. Migration v173 added password_hash, password_salt, view_cap, view_count, last_viewed_at, notify_on_view to the shares table + a share_view_events table (since retired as a writer — no per-view rows are written now). Migration v180 added share_send_log. Migration v181 added per-event privacy hashes (country, ip_hash) on share_view_events (see src/main/db/queries-share-view-events.ts).
  • Mobile push coverage. SHARE_UPDATED reaches the phone — it is in INBOX_ALLOWED_CHANNELS in src/main/services/web/web-access-push-filter.ts, so the WS bridge forwards it to the mobile/web renderer. The one renderer listener, the app-wide SharesLiveSync (useIpcListener), re-reads the phone's share list, @mentions and unread total on each push. The push carries only { action } and is coalesced on the push bus, so a burst reaches the phone as at most two re-reads per 50 ms. The viewer's keyboard-dismiss push WEBVIEW_GUEST_DISMISS (Escape/Ctrl+W forwarded out of the popup's <webview>) is the opposite: it is desktop-only, listed in DESKTOP_ONLY_CHANNELS in tests/unit/lint/14/mobile-push-listener-coverage.test.ts — mobile web has no <webview> guest, and the mobile viewer closes via its X button.
  • Modal lazy-loading. Only PastePublishModal remains as a modal in this integration. It's React.lazy()-imported inside SharesSidebar.tsx per the heavy-modal contract — the chunk only downloads when the user clicks + Publish. (SharesEditModal and SharesSendModal no longer exist — both flows are now inline in SharesDetailPane.)
  • SHARE_SEND IPC. Channel registered in share-handlers.ts. Schema is shareSendSchema in src/shared/ipc-schemas.ts — { shareId, channelKind: 'gmail'|'sms'|'slack', recipient: string(1..1000), message?: string(0..5000) }. Handler validates the share is published / not revoked / not expired, inserts a share_send_log pending row (so a thrown channel call still leaves an audit row), dispatches through gmailApiService.sendEmail, pushbulletService.sendSms, or slackService.sendMessage. Flips the log row to sent / failed, emits SHARE_UPDATED with action 'sent' or 'send-failed', and tracks a 'share', 'send' event with the channel kind. Returns { success: true, data: { entry } } even on channel-level failure — the renderer keys off entry.status === 'failed' so the inline panel stays open.
  • Data layer. share_send_log table added in migration v180 (DDL + indexes in src/main/db/database.ts). Query layer is src/main/db/queries-share-send-log.ts: insertSendLog, updateSendLogStatus, getSendLogById, listSendLogForShare. CHECK constraints enforce channel_kind IN ('gmail','sms','slack') and status IN ('pending','sent','failed'). Indexes on share_id and created_at keep the list query fast.
  • Drag-and-drop fan-out. The HTML5 drop events are owned by useFileDropZone from src/renderer/src/hooks/useFileDropZone.ts (handles the drag-counter, Files-type filter, and preventDefault on dragover). The per-file IPC fan-out lives in publishDroppedFiles from src/renderer/src/features/shares/publish-dropped-files.ts, which: (a) resolves each File's OS path through preload's webUtils.getPathForFile (Electron 39 dropped the renderer-side File.path), (b) calls IPC.SHARE_PUBLISH_ARTIFACT once per file, (c) maps the seven structured share-artifact-service error contract strings (outside-allowlist, unsupported-type, magic-byte-mismatch, empty-file, size-cap, firebase-upload-failed, firebase-quota) to user-friendly sentences, (d) returns a single PublishOutcome = { ok, failed[] } the sidebar collapses into one toast. Synthetic Files (no backing path) and browser mode both short-circuit without ever invoking IPC.

Full-page screenshot

Both in-app share viewers — the quick opener (FloatingShareViewer, the full-size popup that opens share links in-app, yours or a teammate's) and the manager viewer (ShareViewerToolbar, the detail-pane view/fullscreen overlay) — carry a Screenshot button that copies the ENTIRE scrollable shared page to the clipboard as a PNG.

  • A separate capture path. Electron's capturePage() only captures the visible viewport, so the button instead drives a Chrome DevTools-protocol capture (Page.captureScreenshot with captureBeyondViewport) against the share's <webview>, capturing the whole page in one image.
  • Desktop-only. The button renders only in the desktop app — a mobile/web renderer has no embedded <webview> to capture — and stays disabled until the page has loaded. Copy URL works everywhere.
  • Copies to the clipboard. On success a toast confirms "Full-page screenshot copied to clipboard"; a very long page is clamped to a safe maximum (12,000 px/edge) with a "(very long page — trimmed)" toast. Failures surface a friendly message, never a raw error. The capture and clipboard write happen in the main process, so image bytes never round-trip back to the renderer.
  • Security. The capture only ever targets the share's own <webview>; a forged or foreign target id, the main window and agent tabs are all refused.
  • From the CLI. An agent presses the same button with POST /share/:token/screenshot — see Pressing the viewer buttons from the CLI on part 1.
  • Copy URL. The quick opener's header also carries a Copy URL button (the canonical CopyConfirmButton with the "Copied ✓" confirmation), on desktop and mobile, matching the manager viewer's header band.

Implemented by the shared useShareWebviewCapture hook + ShareScreenshotButton component; the main-process capture is captureShareWebviewFullPage() behind the IPC.UI_CAPTURE_SHARE_FULL_PAGE channel.

The overview, the other parts, and everything else worth reading next all sit on Shares view (master/detail sidebar + in-app webview viewer for shared links).

Last verified 2026-11-10