FW Lite plugins MVP: resource-backed storage, hardened API v1, research-backed trust UX

[myieye]

Builds on the plugins MVP branch (claude/nice-swirles-1986fb) and reworks it into its shippable shape. A plugin remains one self-contained HTML file running in an opaque-origin sandboxed iframe against a small, stable window.fwlite API.

Persistence. Plugin HTML no longer lives as a text column in the CRDT. The Plugin entity carries only metadata (name, description, declared manifest, file size, MediaUri); the HTML is an immutable, content-hash-named media resource on the same path audio/pictures use — offline-pending upload, download on demand, synced through hg send/receive under LinkedFiles/Plugins/, visible (inert) to FLEx. Edits upload a new file and repoint the entity, so cached/synced copies can never go stale. Since nothing shipped, the two plugin migrations are squashed into one and the change classes redefined; the 3 MB SignalR message-size bump is reverted because HTML no longer travels inline. The manifest (fwlite-plugin-permissions / -contexts / -requires metas) is extracted into the entity at save time so lists and the entry menu never need the file, while consent and the sandbox always re-parse the actual HTML.

API v1 hardening. A compile-time-checked interface + arg-decoder table replaces the string-switch dispatch. Writes now require a declared edit permission — a read-only plugin can never even pop a write dialog. Comments/history become capability-gated areas a host may not support (a future FieldWorks host won't), advertised in the init message and declarable as requirements so hosts can warn before launch. updateEntry gets compare-and-swap semantics (new conflict error code): before must match the entry's current state, which makes the approval dialog provably show the write's real effect — previously a plugin could fabricate before to disguise what it was overwriting.

Trust UX (per permission-fatigue research: VS Code workspace trust, Android/iOS runtime permissions, Office trusted documents, NN/g on dialog habituation): the write dialog gains Always allow for this plugin, pinned to a content hash per project + device; trusted writes surface as ambient notifications instead of dialogs; the grant survives your own local edits but downgrades to ask-again when changed code arrives via sync; revocation is one tap from the plugin card or the run toolbar. Creating a plugin yourself counts as run consent. Write summaries are now complete recursive diffs (a hand-picked field list could be smuggled past), rendered with the app's own field names ("Sense 1 Gloss (en)"), bidi/control characters stripped, no silent truncation.

Sandbox honesty. A frame can always navigate itself (no CSP directive or sandbox flag stops it), so the offline guarantee was overclaimed. The consent card now says "not allowed to use the internet" rather than "no internet access", and the run view detects a plugin leaving its document, stops it, and tells the user.

Reviewer notes / follow-ups

• Plugin files upload into LinkedFiles/Plugins/<fileId>/plugin-<hash>.html. Since deferred (pending) uploads can't carry metadata on current Harmony, the subfolder rides in the file's local cache path and is derived at upload time; once the media-manager branch (Media manager #2358, Harmony resource metadata) lands, that carrier can be dropped in favor of the new LcmFileMetadata.LinkedFilesSubfolder field.
• Old plugin resource files are never deleted (orphaned versions accumulate in LinkedFiles, same as replaced media) — GC is a follow-up.
• Trust/consent grants are deliberately device-local localStorage (a teammate's click must not authorize code on your machine).
• Serialization of the redefined change classes is covered by regenerated regression snapshots.
• Interaction notes with the media-manager PR are in a comment below.

Tested: LcmCrdt.Tests plugin + media-subfolder + serialization/snapshot suites, dotnet ef migrations has-pending-model-changes clean, 62 plugin vitest tests, svelte-check/eslint clean, 6 core Playwright flows, and all 27 example plugins run against the demo project (migrated into the new tests/ui suite after merging develop).

Plugin cards with capability badges	First-run orientation card
Write approval with human-readable diff + Always allow	Trusted plugin: toolbar indicator + ambient notification
AI prompt generator	Example gallery
Dictionary Stats example	Lexicon Galaxy example

(Screenshots live in commit a509dd0, which is reverted on the branch so they don't ship.)

🤖 Generated with Claude Code

https://claude.ai/code/session_018yusi3xgjHHaA9w18itSeD

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 5fbb218a-b358-43e6-97d6-9387e240767a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/plugins-mvp-review-y9lx01

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Awaiting the start of a new Argos build…

[myieye]

The 4 Argos diffs are the expected ones: all four project-view snapshots (default + entry-selected, light + dark) include the sidebar, which gains the new Plugins nav item in the demo project. No other visual changes.

---

Generated by Claude Code

[myieye]

Interaction notes: plugins × media manager (#2358) — from a review of both branches, for whoever merges second:

• Guaranteed conflicts in LcmMediaService.SaveFile/UploadResource, IMediaServerClient (this PR adds linkedFilesSubfolderOverride to UploadFile; Media manager #2358 makes the interface internal, adds GetFileMetadata, changes MediaUploadFileResponse), and LcmFileMetadata (Media manager #2358 adds SizeInBytes, this PR adds LinkedFilesSubfolder) — union all three.
• Simplification after Media manager #2358: its Harmony rc.211 bump persists resource metadata and passes it to UploadResource even for pending uploads — so the cache-path carrier for the subfolder in this PR's LcmMediaService can be deleted and metadata.LinkedFilesSubfolder passed directly. It also makes the subfolder CRDT-synced, giving the media manager a clean key to group or hide plugin files (today they'd show as opaque plugin-<hash>.html rows with no preview — worth a "Show app files" toggle or a Plugins group there).
• Merge landmine: Media manager #2358's UploadResource reconstructs LcmFileMetadata positionally from the server response — LinkedFilesSubfolder would be silently dropped; use a with {} copy instead.
• When delete lands in the media manager (primitives exist, UI doesn't yet): deleting a plugin's backing file would dangle the Plugin entity's fileUri — that flow needs a referenced-by check or should exclude the Plugins/ subfolder.

Also: the Argos e2e diffs are the same expected change as the default build — snapshots that include the sidebar now show the Plugins nav item.

---

Generated by Claude Code

[hahn-kev]

this results in using a bunch of extra memory. Ideally we would load the doc like this:

// Point to a blank slate first
iframe.src = 'about:blank';

iframe.onload = () => {
    const doc = iframe.contentDocument;
    doc.open();
    doc.write(largeHtmlString);
    doc.close(); 
    // largeHtmlString can now be safely GC'd if no other references exist
};

most importantly though, we don't want to store the html string anywhere, we want the GC to be able to reclaim that memory.

[myieye]

Fixed in 89f0d287 — with one deviation from the suggested mechanism: document.write needs iframe.contentDocument, and the sandbox deliberately omits allow-same-origin, so the plugin frame is opaque-origin and the parent can't touch its document. The equivalent that keeps the sandbox is a Blob URL: the composed document goes into a Blob the iframe loads via src, so neither the raw HTML nor the srcdoc string is retained anywhere — state now holds only {manifest, hash, docUrl}, the strings are GC-able as soon as the load scope ends, and the URL is revoked when the state is replaced or the view unmounts. Reload reuses the same Blob; the on-disk resource cache stays the source of truth. Verified the navigation-teardown load counter doesn't false-positive on src-based loading (all 6 core flows + the 27-example sweep pass).

---

Generated by Claude Code

[myieye]

Correction: the commit is eecd1c3 (not 89f0d287).

---

Generated by Claude Code