Share Comments (inline and general commenting on shared links)
Viewers of an Omniscio Share can leave comments directly on the share page. Five comment types exist: General comments — free-form, not anchored to any content position. Inline text-selection comments — the viewer selects text on a markdown / plain-text / code share, and the comment anchors to that selection.
On this page
What it is
Viewers of an Omniscio Share can leave comments directly on the share page. Five comment types exist:
- General comments — free-form, not anchored to any content position.
- Inline text-selection comments — the viewer selects text on a markdown / plain-text / code share, and the comment anchors to that selection.
- Coordinate-pin comments — on image and PDF shares, the viewer clicks a point on the content and the comment anchors to those x/y coordinates (rendered as a numbered pin).
- Iframe-bridged text-selection comments — for HTML and React shares that run inside a sandboxed iframe, the share page uses
postMessageto bridge the viewer's text selection out of the iframe so an inline comment can anchor to it. - Video-timestamp comments — on a shared screen recording, the viewer pins a comment to a moment in the video ("Comment at 2:35"); clicking that comment later seeks the video to the moment. This is the Loom-style timestamped-comment surface.
Comments appear in real time for all viewers (Firestore live subscription) and are mirrored back to the desktop app so you can see them without opening the share page.
Where to find it
Commenting happens on the published share page, not inside the app: a floating comment button sits at the bottom-right of every share page that has commenting enabled, and signing in with Google is required to post. The capability itself is live for everyone — there is no Lab toggle — and each share carries its own "Allow comments" toggle in the Shares detail pane.
How it behaves
How to use it
Turn commenting on for a share
Share Comments has shipped — the commenting system is already there for every user, so
there is nothing to reveal in Settings → Lab and no AMC_SHOW_SHARE_COMMENTS reveal left to
do. What you turn on is commenting for a share, from the Shares detail pane's
"Allow comments" toggle.
Who can read a share's comments
Every share carries an audience its sharer chose, and it is enforced on the server, not just in the interface:
- Anyone with the link — the default, and what every share published before this choice existed still does. Any signed-in reader holding the link can read and post.
- Only my workspace — only people in the sharer's Omniscio workspace, plus the sharer themselves. A signed-in reader outside it is refused the thread and told why; they cannot post either. A sharer who belongs to no workspace is the only reader.
The workspace is recorded on the share at the moment the choice is made, so changing your active workspace later does not change who can read an old link. Switching between the two rebuilds the published page in place, on the same link.
The thread also follows the page's own locks. A reader who cannot open the page cannot read or post in its thread either:
- A password — the reader must have entered it. After they do, the comment box asks the share
server for a comment pass (
POST /s/<token>/comment-grant, sent with their sign-in), and the server gives one only to a browser that holds the share's unlock cookie. The pass lasts 6 hours, belongs to that one signed-in account, and stops working the moment the password changes. - A view limit — only a viewer the limit already counted gets a pass, so they keep commenting after the limit is reached, while someone who never opened the page gets nothing.
- Only my workspace (who can open it) — only the sharer and live workspace members; no pass is needed.
- Taken down, or the sharer's account suspended — the thread is closed to everyone, the sharer included, until the page is restored.
The sharer never needs a pass on their own share. A page carries a frozen copy of the comment box from the day it was published, and a comment box older than the pass never asks for one. So on a password or view-limited page published with an older comment box, only the sharer can still read or post comments. Once the comment box that asks for a pass ships, publishing that page again gives it the new box.
Marking a comment resolved is the author's or the sharer's, and it records who did it. A comment always starts unresolved; resolving one records the person who clicked, with the server's own time, and undoing it clears both. A commenter can neither be born marked resolved in the sharer's name nor have their click credited to the sharer.
On the share page (viewer side)
- Open the comment sidebar. A floating comment button sits in the bottom-right corner of every share page that has commenting enabled. Click it to open the sidebar.
- Sign in. Google sign-in is required to leave a comment. Click "Sign in with Google" in the sidebar; a small window opens Omniscio's own sign-in page (
/s/<id>/comment-sign-in), which signs you in with Google and closes itself. If the browser blocks that window, the same page opens in the tab and returns you to the share afterwards. The share page itself never loads Google's sign-in script (RT-F003): only that sign-in page, which shows no shared content, does. Under the button sits a short notice stating what signing in stores (your Google name, profile-photo URL, email and account id, plus your comments), that other people viewing the share and the share's owner can see them, how long they are kept, and links to the Privacy Policy and to the deletion route — signing in here creates an account in the company's Firebase project, so the collection has to be disclosed at the point it happens. - Leave a general comment. Type in the sidebar's comment box and submit. Comments support inline formatting:
**bold**,*italic*,~~strikethrough~~,[link text](url), and> blockquote. Use Ctrl+K (Cmd+K on Mac) to insert a hyperlink around selected text. A formatting hint below the text area shows the available syntax, and names the shortcut for the viewer's own computer: Cmd+K on a Mac, iPhone or iPad, Ctrl+K everywhere else. Ctrl+Enter (Cmd+Enter on Mac) posts. - Leave an inline comment (static shares). Select text on a markdown, text, or code share. An SVG share is shown as a picture, so it takes general comments only. A small "Comment" tooltip appears near the selection. Click it to open a reply box pre-anchored to the highlighted passage. On a phone or tablet, press and hold to select: the Comment button appears just below the selection once you stop adjusting it, clear of the selection handles, and tapping anywhere else dismisses it. The same works inside HTML and React shares.
- Leave a coordinate-pin comment (image / PDF shares). Click anywhere on the image or PDF. A numbered pin drops at that point and the sidebar opens a reply box anchored to those coordinates.
- Leave an inline comment (HTML / React shares). Select text inside the sandboxed iframe. The share page bridges the selection out via
postMessage; the same "Comment" tooltip appears and the flow continues as for static shares. - Leave a video-timestamp comment (screen-recording shares). As the video plays, the sidebar shows a "Comment at M:SS" button reflecting the current position. Click it to attach that moment to your comment (shown as a "▶ 2:35" chip on the comment); clicking the chip later seeks the video back to that moment. Emoji reactions work the same as on any share.
- Reply to a comment. Click "Reply" on any comment. A reply indicator appears above the composer showing a truncated snippet of the parent comment's text (Messenger/Slack style). Click the snippet to scroll back to the parent comment. After posting, the reply displays a quoted context snippet of the parent above the reply text.
- Delete a comment. Your own comment can be deleted by you; any comment on a share can also be deleted by the share's owner, who is the person that receives takedown and erasure requests for the page. Deleting a comment that has replies removes only that comment — the replies stay and are shown at the top level, so their authors keep their own delete path. The confirmation dialog says exactly that.
- Real-time updates. New comments from other viewers appear instantly (Firestore
onSnapshotsubscription). No refresh needed. - See where the comments are, and jump to them. While the sidebar is open, every text-anchored comment is marked on the page itself — a gold dotted underline with a small dot — so you can see which passages have feedback. Click a comment's quoted-text chip in the sidebar and the page scrolls to that passage and briefly highlights it. (This works on HTML / React shares too, where the content runs in a sandboxed frame.)
- Keyboard. Esc cancels a reply you started; a second Esc closes the comment panel. Esc never closes the panel while the comment box (or a link box) still holds text you have not posted, because closing would throw that text away. Space or Enter presses a quoted-text chip, the parent snippet above a reply, and the "Replying to" bar.
- Phones and tablets. On a touch screen every comment control is at least 44 pixels tall and wide: Reply, Resolve, Delete, reactions and the reaction picker, Post, add-link, the remove buttons, the floating Comment button, the timestamp button, Sign out, the close button and the error dismiss. Below 640 pixels wide the panel covers the whole screen instead of squeezing the page.
tests/e2e/ui/share-comment-page-phone.spec.tsproves this at phone size on the built comment bundle: the box opens full width and closes on Esc, a signed-in viewer types a comment and taps Post, and Post, add-link and the floating Comment button measure at least 44 pixels as real controls (the reaction picker and the rest through the touch-screen style rule). The spec blocks every Google request, so a Post there ends in the composer's "Couldn't post" error with the text kept. Posting all the way to the server is proven only by theshare:comments-e2espec, which writes to production and runs at desktop size. - Language. Every word the comment panel shows comes from one strings table. The panel uses the viewer's browser language when a table for it exists and English otherwise, and any word missing from a partial table falls back to English. Today only English ships, so every viewer sees English; adding a language is one new table and nothing else. Names, comment text and dates are shown as they are.
On the desktop app (author side)
- Shares detail pane. Open the Shares sidebar, select a share. A collapsible Comments section appears in the detail pane with a comment count in the section header (e.g. "Comments (3)"). It is the same section in both layouts: view mode shows it underneath the viewer, in a scroll region of its own, so a share you are reading in the in-app viewer still shows its comments. A
#commentslink opens the share in view mode already scrolled to the newest comment (with "Open shares in app" on). A share with no comments shows no Comments card in view mode. - Inline anchor highlights. For HTML and React shares, anchored comments are visually marked in the preview iframe with a gold dotted underline and a superscript dot indicator. Click a highlight mark to scroll the matching comment into view in the comment list. Highlights update reactively when comments are added or removed.
- Allow comments box. The per-share Allow comments box is in the detail pane's Edit form (the share's details form, beside the notify and mute boxes), not inside the Comments section. It turns commenting on or off for that one share, and changing it rebuilds that share's page. New shares start with the global
shareCommentsDefaultOnsetting. The box is hidden while Share comments is switched off (see Turning Share comments off). While comments are on, a Who can read comments picker below it chooses Anyone with the link (the default) or Only my workspace — see Who can read a share's comments. - New comments live in Shares, not the inbox. Since 2026-10-08 a new comment never creates an inbox item. Instead, the Shares row in the sidebar shows a count of unread comments plus unseen @mentions (gated on
shareCommentsNotifyInbox). Every share with unread comments is pinned in a New comments section at the top of the Shares list, even an expired or revoked one, so that count always points at something visible. Each pinned share shows an "N new" pill. Beside it, a row whose share has comments carries a muted total-comment count (both numbers are computed in the main process, so the desktop and the phone agree), so a share whose comments are all read still shows how many it has. Opening a share tags its unread comments "New" and marks them read, and the share drops back to its usual place in the list. @mentions of you on other people's shares are listed under Mentioned you. - An @mention buzzes your phone; a new comment does not. Since 2026-11-05 (the owner's answer 2A) a new @mention of you sends a phone notification titled "<author> mentioned you on <share>" (or just "Mentioned you" when either name is missing) with the comment's text. Tapping it, or clicking the mention's row under Mentioned you, opens the share in Shares scrolled to that comment (a comment inside a resolved thread opens the resolved section first); a mention on someone else's share opens that share instead. It buzzes only for a mention this computer sees for the first time, that is unread and less than 24 hours old, and never for the history it reads the first time you sign in. Switching Share comments off (Allow comments on new shares), the Notify me about comments setting (
shareCommentsNotifyInbox), quiet hours and Silence each turn it off, and every Shares phone notification shares one limit: at most 5 in 10 minutes and one per subject per hour. With content-free phone notifications on (the default), the native phone app's notification says only "Shares / Open Omniscio to see it". Mentions still never become inbox cards. - @mentioning someone on the share page shows their name while you type. Typing
@in the share page's comment box lists the people on that share; picking one puts@<their name>in the box (the same as Team Chat), never their account id. When you post, each picked name is stored as that person's id, so the posted comment shows their name and notifies them exactly as before. If two people share a name, or a person has no name, the box shows their id instead so the right person is notified. A share page carries the comment widget it was published with, so this applies to shares published from an app build that has it, once the share servers carry that widget's hash.
Turning Share comments off
Share comments has ONE off switch: Settings → Share Comments → "Allow comments on new shares" (the shareCommentsDefaultOn setting, default on). It is the feature's "hide it again" switch for the Feature Release Checklist (item 18). Share comments started hidden behind a Lab toggle and was announced for Lab dogfood on 2026-07-30; it is shipped now, so there is no Lab toggle, and the old Lab key shareCommentsEnabled is retired — the registry entry reads shareCommentsDefaultOn instead (settingControls), so the one visibility gate honors it.
What "off" means:
- New shares (documents, pages and screen recordings) publish with no comment box. That stays true for the page's whole life: turning the switch back on later does not add a comment box to it. Republish the share with the switch on to give it one.
- Shares you already published keep their comment box. A share's page is built once, at publish time, with the comment box baked in, so the switch cannot reach it. Viewers can still comment there. To take the box away, republish that share while the switch is off (the page is rebuilt without it). The per-share "Allow comments" box is hidden while the switch is off, so this is the way to close an old share's comments.
- In the app, the Shares panel shows no comments: no Comments card in the detail pane (Edit or View), no comment count or "N new" pill on rows, no "New comments" section (a share with unread comments goes back to its usual place under Live or Archived), no "Mentioned you" section, and no count on Shares in the sidebar. The per-share "Allow comments" box, the "Who can read comments" picker and the Team Chat channel picker in the publish dialog are hidden too.
- Nothing is deleted. Comment counts and @mentions keep syncing in the background, so turning the switch back on shows everything, current, at once.
- The agent's read-only CLI routes still answer (
GET /share/:token/comments,GET /share/mentions), so an agent can still read comments for the owner. Every field a viewer can write reaches the agent inside the untrusted-content frame: the comment text, the anchor's quoted text and selector, and each mention entry; a field the comment does not carry stays absent.
Team Chat integration
When publishing a share, you can optionally pick a Team Chat channel to link. When a viewer leaves a comment on that share:
- The
onCommentCreateCloud Function fires. - If
shareCommentsCrosspostTeamChatis enabled and a channel was linked during publish, the function posts the comment text as a thread reply in that Team Chat channel. - Team members in the channel see the comment without opening the share page.
Cross-posting is one-way: Team Chat replies do not appear on the share page.
How it works
Data model
Comments are stored in Firestore at shares/{token}/comments/{commentId}. Each comment document contains:
authorUid,authorName,authorPhotoURL— from Google sign-in. OnlyauthorUidis identity: the name and photo copy the commenter's own profile, which they can change, so the owner's powers and the owner marker follow the uid. The photo must be a Google profile photo (lh<N>.googleusercontent.com) or empty; a comment carrying any other image address is refused, so a commenter cannot make every reader's browser call a server of their choosing.text— the comment body (plain text with optional Markdown-style formatting; rendered at display time, not stored as HTML).createdAt— server timestamp.anchor— optional object describing the comment's position:{ type: 'text-selection', quotedText, selector, startOffset, endOffset }for inline text,{ type: 'coordinate', x, y }for image/PDF pins,{ type: 'video-timestamp', timeMs }for a moment in a recording, or absent for general comments.
Every part of a comment is size-limited, not just its words: at most five attachments of 2,048 characters each, twenty @mentions and one anchor, plus an overall size limit on the comment. A comment past any of those limits is refused, so one visitor cannot pad a thread with hidden data that every other reader — and the app's own comment check — would then download.
Each viewer's reactions on a comment live in one doc at shares/{token}/comments/{commentId}/reactions/{uid}, holding emojis (up to five), uid and updatedAt. Every emoji must be one of the five the page offers (👍 ❤️ 😂 🤔 🎉); a reaction carrying anything else (another emoji, a sentence, a non-text value) or any other field is refused, so one viewer cannot plant a value that breaks the comment panel for everyone else. A reaction can only be changed while the page still allows comments: once the share is switched off, expires, is taken down, or has comments turned off, the existing reactions stay but cannot change.
Share page comment sidebar
The comment sidebar is a standalone React app bundled as an IIFE and injected into the share shell HTML at publish time. It mounts its own React root, manages its own Firebase Auth + Firestore connection, and renders the comment list + input. Its Firebase Auth is started without Google's popup helper, so no Google script is loaded on the share page; signing in happens on the first-party sign-in page, which writes the session to the same browser storage the sidebar reads. Shares published before this change carry an older sidebar, and the share server swaps it for the current one when it serves the page. The sidebar communicates with the host page (for text-selection anchoring and coordinate pins) via DOM events and postMessage (for iframe-bridged selections).
The sidebar takes its colours AND its light/dark mode from the page hosting it. A shell that declares a theme in data-theme on <html> is followed exactly, including a viewer flipping the page's own toggle; the sidebar only falls back to a stored preference and then the operating system's setting when the page declares nothing. A screen-recording share paints a dark page and declares it, so its comment panel is dark in both themes — it is no longer a white panel over a black page for a viewer whose system is in light mode.
Reply comments display a reply context snippet -- a clickable quoted preview of the parent comment's first line (truncated to 100 characters with ellipsis). Clicking the snippet scrolls to and briefly flashes the parent comment. The reply indicator above the composer also shows this snippet with the parent's author name and a cancel button. Both surfaces have light and dark mode CSS variants. The desktop mirror (ShareCommentsList.tsx) renders the same snippet using Tailwind surface-* tokens and the shared truncateEnd utility.
Cloud Function: onCommentCreate
A Firestore-triggered Cloud Function (onCommentCreate) runs on every new shares/{token}/comments/{commentId} document. It:
- Reads the parent share document to find the linked
teamChatChannelId. - If a channel is linked and cross-posting is enabled, posts the comment to that Team Chat channel as a thread reply.
- Writes one
userMentionAlerts/{uid}/items/share-mention-{token}-{commentId}pointer doc into the per-user cloud mention collection of each mentioned participant (read by the desktop mention poll for "Mentioned you"; it is not the app inbox) (capped, budgeted, and restricted to people already in the conversation). The pointer holds only the token and comment id — the author name/photo, share label and a 200-char preview are filled by the mention poll from the comment and share at read time, so no PII copy is kept in that collection.
It used to also write a shares/{token}/alerts/{commentId} "alert document for the desktop poller" — that copy is gone. Nothing ever read it: the desktop poller reads the share mirror doc's lastCommentAuthorName / lastCommentAt, and the value it added was a third, unread, non-expiring copy of the commenter's name, photo URL and a 200-character preview. Docs written before that change are still purged whenever the comment is deleted, the share is torn down, or the author's account is erased.
Cloud Function: onCommentUpdate
A second trigger on the same path fires when a comment is edited. It re-writes the Team Chat cross-post in place (only when that message already exists) so the quoted preview follows the edited text. It never creates a cross-post: a mention newly added by an edit does not notify anyone, because adding a mention is a notification decision made by onCommentCreate, where the participant restriction and the per-author fan-out budget live. The mention pointers carry no text of their own, so an edit needs no mention-copy refresh — the poll reads the comment fresh.
Cloud Function: onCommentDelete
Deleting a comment deletes its mention pointers and any legacy alert doc. A share teardown (unpublish, expiry, or account erasure) needs no mention-copy sweep: the pointers hold no PII, so a pointer left in another user's inbox after the comment is gone shows nothing.
Account erasure
When a commenter's account is erased, eraseShareComments (firebase/functions, global-auth/user-erasure) walks every comment they authored and redacts the document rather than deleting it, so a threaded reply is not orphaned. The body becomes [removed — account deleted], the display name becomes [Deleted User], and the avatar URL, the quoted anchor (a copy of the page text they selected), the attachment URLs, the mention list and authorUid are all cleared in the same write — an erased commenter's words are gone from the page, and nothing about who they were is left beside the tombstone.
The same pass deletes the copies that live outside the comment: any legacy alerts doc for it, the per-share mention and comment-notify budgets keyed by their uid (shares/{token}/mentionFanout/{uid}, commentNotify/{uid}), and their own reaction docs on other people's comments. It also takes their uid out of other people's comments — the mentions arrays that name them and the resolvedBy stamp they left behind — while leaving those comments' own words and authors untouched. The share's own lastCommentAuthorName (the denormalized name the desktop poller shows) is cleared when the comment being redacted is the newest one on that share, which is the case where it holds their name; a share whose newest comment belongs to someone else keeps that person's name. Reactions are keyed by uid as the document id, which a collectionGroup query cannot match, so each reaction doc also carries a uid field (written on create and refreshed on every later toggle), and reactions.uid has a COLLECTION_GROUP index in firebase/firestore.indexes.json. A reaction doc last touched before that field existed is unreachable until it is toggled once or stamped by the one-time backfill (firebase/functions/scripts/backfill-share-reaction-uid.mjs, which takes --dry-run and is safe to re-run); until either happens it goes only when its comment or share is deleted.
Erasure pages the comments in document-path order and commits them in budgeted batches, so a prolific commenter cannot blow Firestore's write cap; a page cap or an error leaves a residual that the daily deletion-residuals reconciler re-drives. Each reaction doc (shares/{token}/comments/{id}/reactions/{uid}) carries a uid copy of its id, because a collection-group query cannot read the doc id; firebase/functions/scripts/backfill-share-reaction-uid.mjs stamps it onto older reaction docs and refuses to run without an explicit target project.
Desktop poller
A periodic task on the desktop mirrors comment counts from Firestore to the local SQLite shares table. On each tick it:
- Reads comment counts for shares with
comments_enabled = 1. - Updates the local
comment_countcolumn. - Creates no inbox item for a new comment (since 2026-10-08, the owner's decision). The new count raises the share's unread number, which surfaces in Shares: the sidebar count (when
shareCommentsNotifyInboxis on), the "New comments" section and the row's "N new" pill. - Polls the mention relay for @mentions of the signed-in user and stores each in the local
share_mentionstable for the "Mentioned you" section — never the inbox. An empty poll widens the next one toward 5 minutes and a real mention snaps it back to 60 seconds, so a user receiving no mentions costs few Cloud Function calls; a wider window only delays a mention, never drops one. The poll's high-water cursor is saved in the app's settings, so a restart does not re-read the whole mention history; a settings read failure falls back to a full re-poll rather than stopping the tick.
Comment inbox cards raised before 2026-10-08 still work: their "[View and respond]" link carries a #comments URL fragment that the renderer's interceptShareUrl recognizes, setting pendingCommentScroll in the share store so the Comments section scrolls to the newest comment on open.
Inline anchor highlights (desktop preview)
When the shares detail pane displays an HTML or React share with comments enabled, SharesDetailPane posts a share-comment-highlight-all message to the preview iframe after it loads. The message carries an array of anchors (comment ID, quoted text, CSS selector, offsets). Inside the iframe, the COMMENT_BRIDGE_SCRIPT (injected at build time into the runnable doc) receives the message and:
- Clears any existing
<mark class="amc-comment-anchor">elements and dot indicators. - For each anchor, tries the CSS selector + offset path first, then falls back to a full-document text search (
findTextInNode). - Wraps the matched range in a
<mark>with a gold dotted underline and inserts a superscript dot indicator. - Attaches click handlers that post
share-comment-anchor-clickback to the parent, which scrolls the matching comment row into view and pulses it with the sharedsetting-highlight-pulsekeyframe.
The highlight effect re-fires whenever the Zustand commentsByToken slice changes, so highlights stay in sync with comment additions and deletions. An empty anchors array clears all marks (handles the case where every anchored comment is deleted).
Inline anchor highlights + click-to-scroll (web viewer)
The published web viewer (share-comment-app, at shares.omniscio.com) does the same for the person reading the share. While the sidebar is open, CommentSidebar.tsx (via iframe-highlight.ts) posts share-comment-highlight-all with the anchored comments to the content iframe, so the same gold dotted-underline <mark> + dot indicators appear on the page. Because the author document renders only once the tab is visible, the bridge posts share-comment-bridge-ready when it loads and the shell re-sends the anchors then — so the marks appear even for a share opened in a background tab.
Clicking a comment's anchor chip posts share-comment-scroll-to. The bridge flashes the mark (.amc-comment-anchor-active), scrolls it into view, and — because an opaque-origin sandboxed frame cannot scroll its parent — reports the mark's unscaled offset as share-comment-scroll-to-y. Whichever frame is the author's parent then scrolls the outer viewport to it: the FIT_HOST_SCRIPT / RESPONSIVE_HOST_SCRIPT (scaling by their fit factor) for a scaled render, or the shell's scrollContentToY for a directly-served one. The whole feature is baked into the artifact at publish time, so an already-published share picks it up only when it is re-published.
Recording shares — the comment shell + video bridge
A screen-recording share is a <video> served in an opaque-origin sandbox (/s/<token>/run) where the comment app's Firebase Auth cannot run. So — exactly like HTML/React shares — a recording that hosts comments is published as a first-party shell at /s/<token> (buildRecordingShellHtml) that frames the /run video doc in an iframe and hosts the comment app beside it. The /run viewer carries a small share-comment-video-* bridge (VIDEO_COMMENT_BRIDGE): it posts the live playback position UP (share-comment-video-time) so the sidebar's "Comment at M:SS" button stays current, and seeks the <video> when the sidebar posts share-comment-video-seek {ms} DOWN (validated finite ≥0, clamped to the video's duration). The comment app treats artifactKind: 'video' as its own mode — no text-selection or coordinate-pin capture. Reactions, notify-on-comment, and the Firestore/rules/poller path are the SAME as every other share (no kind-specific backend). With Share comments switched off (shareCommentsDefaultOn off), a recording share publishes with no shell — the plain /run viewer, exactly as a recording without comments.
IPC channels
SHARE_COMMENTS_LIST(invoke) — returns the list of comments for a given share token, used by the Shares detail pane Comments section.SHARE_COMMENTS_UPDATED(push) — emitted when the poller detects new comments, so the detail pane can refresh.
Troubleshooting
Comments not showing on the share page? Two things gate it. (1) Share comments must be on — Settings → Share Comments → "Allow comments on new shares" — at the moment the share was published; a share published while it was off has no comment box until it is republished with it on. (2) That share's own "Allow comments" box (in the detail pane's Edit form) must be on. The feature is shipped, so there is no Settings → Lab step.
Comments disappeared from Shares? Check Settings → Share Comments → "Allow comments on new shares". With it off, the Shares panel hides every comment surface. Nothing was deleted; turn it back on and they return.
Can't sign in on the share page? Sign-in opens Omniscio's own sign-in window. If the browser blocks it, the sign-in page opens in the same tab instead, so it should never fail silently. If you finish signing in but the sidebar still shows the sign-in button, reload the share page: the session is saved in the browser and is picked up on load. Private windows that block site storage cannot keep a session at all.
Cross-posting to Team Chat not working?
Three things must be true: (1) a Team Chat channel was linked during publish, (2) shareCommentsCrosspostTeamChat is enabled in Settings, and (3) the Team Chat integration itself is enabled and connected. Check all three.
No count on Shares for a new comment?
New comments never create inbox items; they show in Shares. Verify shareCommentsNotifyInbox ("Notify me about comments") and Share comments itself are on. The desktop poller runs on a 60-second interval (wider when idle), so there may be a short delay before the count appears.
Clicking "View comments" on an old inbox card doesn't scroll to the comment? Only cards raised before 2026-10-08 carry this link. The scroll effect waits for comments to load from the backend. If the share's comment list is empty (all comments were deleted since the notification), the scroll is skipped gracefully. If the share itself was deleted or revoked, an error toast appears instead.
Comments appear on the share page but not in the desktop detail pane? The desktop mirrors comments via a periodic poller, not a live subscription. The desktop checks about once a minute while your shares are active; when nothing has happened for a few minutes it slows to once every 5 minutes, so the first new comment after a quiet spell can take up to about 5 minutes to appear. If they still don't appear after that, check the main process logs for Firestore connectivity errors.
Usage tracking
Share comments are counted on the owner's own desktop, under the share_comment usage entry:
arrivedcounts each time the Shares poller sees new comments on one of your shares, with how many were new (newComments). It fires right after the poller writes the share's new comment total, so one batch of new comments is counted once: a failed write is counted by the next poll that succeeds, re-reading rows that were already counted adds nothing, and a deleted comment (the total going down) adds nothing.viewedcounts each time you open a share that has unread comments. Opening it marks its comments seen and tells every surface (the row's "N new" pill, the sidebar total, the phone) to re-read the share list.- What is NOT counted: viewers posting, replying, resolving or deleting. Those happen on the public share page in the viewer's own browser, which cannot record a desktop event. So the numbers say how many comments reached you and how often you read them, not every action a viewer took.
- No share token, comment text or name is recorded, only the count.
Speed cost
What share comments cost the app, in the four numbers every soft-launch feature reports. Measured Nov 5, 2026; on-screen open time measured Nov 7, 2026.
| Cost | Number | How it was measured |
|---|---|---|
| Startup | Nothing of its own. Comments ride the Shares poller, which starts after the window is up and first checks 60 seconds later. | The comment pass is part of the same deferred poller tick (reconcileCommentStates); see the Shares view page's Speed cost row. |
| Memory | At most 200 stored comments per share on the desktop; nothing kept in memory between checks. | COMMENT_MIRROR_WINDOW trims each share's local comment rows to 200 after every sync. |
| Download size | 665 KB for the comment app a viewer's browser loads with the share page. The desktop reads comments only for a share whose comment count changed, on its regular check. | Size of the production comment app bundle (measured 2026-10-20, see the share-comments map). |
| Open time | Reading one share's comments: within the noise of a trivial request (15 comments, 8.9 KB). Drawing them on screen: 600 ms median (388–645 ms) from clicking a share to all 20 of its comments drawn (runs 388, 395, 600, 629, 645 ms). | Read: GET /share/:token/comments on the live install's most-commented share; 10 runs against 10 runs of a trivial request, medians 136 ms and 131 ms, both carrying the ~120 ms start-up of the calling tool. On screen: Five cold runs of tests/e2e/ui/shares-speed-cost.spec.ts on the cloud E2E runner (the repository's end-to-end run, Nov 7, 2026), one after another, each in a fresh test app seeded with 600 placeholder shares plus one share carrying 20 placeholder comments. The clock starts on the share-row click and stops when all 20 comment rows are in the page; see the Shares view page's Speed cost section for the panel number from the same runs. |
How often it checks for new comments: once a minute while there is activity, slowing to once every 5 minutes when nothing is happening, and back to once a minute as soon as a comment or view lands.
Measure the on-screen time: tests/e2e/ui/shares-speed-cost.spec.ts opens a seeded 20-comment share in 5 cold runs and prints how long its comments take to render, as [shares-speed-cost].
Related
- shares-view.md -- Shares detail pane (where the Comments section and per-share toggle live)
- screen-recorder.md -- Screen Recorder (recording shares host video-timestamp comments via the comment shell)
- share-artifacts.md -- Share publishing (the publish flow that sets
commentsEnabledandteamChatChannelId) - share-cli.md -- CLI endpoints (the
POST /share/publishfields for comments) - team-chat.md -- Team Chat (the cross-posting destination for share comments)
Last verified 2026-11-06