`<iframe/>` Integration

[craquet]

An <iframe/> integration would make it possible to embed the editor in other frontends. RO-Crate information could be exchanged through the postMessage functions. The NovaCrate frontend will need to be reduced a bit to "embedded mode".

Next steps:

1. Design message interface
2. Implement message interface and "embedded mode"
3. Deploy example on GH pages

[koubaa-hmc]

Integration Proposal: NovaCrate Metadata Editor

Objective

To establish a secure, bidirectional communication bridge between the parent application and the NovaCrate iframe for the purpose of editing and synchronizing RO-Crate (Research Object Crate) metadata.

---

Following points are to be discussed

1. Security & Access Permissions

• CSP Headers: Discussion on updating frame-ancestors to allow caller domain.
• X-Frame-Options: Verification that headers are not blocking the embed.
• Authentication: Strategy for passing session tokens (JWT) to the iframe without relying on 3rd-party cookies.

2. Layout & UX Coordination

• Dynamic Resizing: Strategy for the iframe to report its internal height to the parent to prevent double scrollbars.
• Navigation: Rules for internal link behavior (e.g., target="_top" vs target="_self").

3. RO-Crate Data Lifecycle

• Initial Load: How the parent pushes the existing ro-crate-metadata.json to NovaCrate.
• Partial Sync: Strategy for handling large crates via partial entity updates.
• Save/Export: Final handshake for returning the modified JSON-LD to the parent database.

---

Proposed Message Protocol

All communication must use window.postMessage() with a standardised JSON wrapper.

Message Schema (TypeScript)

interface NovaCrateMessage {
  source: 'nova-crate' | 'parent-app';
  type: string;
  version: '0.1';
  payload: {
    crate?: object;      // Full ro-crate-metadata.json
    entities?: object[]; // Partial @graph updates
    height?: number;     // For resize events
    error?: string;      // Error details
  };
}

Event Registry

Message Type	Direction	Description
APP_READY	Iframe → Parent	Iframe is initialized and ready for data.
LOAD_CRATE	Parent → Iframe	Initial push of the full RO-Crate metadata.
UPDATE_ENTITY	Iframe → Parent	Partial Update: Sent when a specific entity in the @graph is modified.
SAVE_CRATE	Iframe → Parent	Final Save: Returns the complete, finalized JSON-LD payload.
RESIZE	Iframe → Parent	Report internal scrollHeight to adjust iframe container.
SYNC_ERROR	Either	Notification of JSON-LD validation failure or origin mismatch.

sequenceDiagram
    participant P as Parent Website
    participant I as NovaCrate Iframe

    Note over P,I: Phase 1: Handshake & Initialization
    P->>I: Load Iframe (URL)
    I-->>P: postMessage: { type: 'APP_READY' }
    P->>I: postMessage: { type: 'LOAD_CRATE', payload: { crate: full_json_ld } }

    Note over P,I: Phase 2: Reactive Editing
    I->>P: postMessage: { type: 'RESIZE', payload: { height: 850 } }
    Note right of I: User edits metadata
    I-->>P: postMessage: { type: 'UPDATE_ENTITY', payload: { entities: [...] } }

    Note over P,I: Phase 3: Finalization
    Note right of I: User clicks "Save"
    I->>P: postMessage: { type: 'SAVE_CRATE', payload: { crate: finalized_json_ld } }
    P->>P: Validate & Persist to DB
    P-->>I: (Optional) postMessage: { type: 'SYNC_SUCCESS' }

Loading

[craquet]

Thanks @koubaa-hmc for the clearly structured notes! I'll just write down some notes here for our meeting later.

Discussion

1. Security

• Most of this will probably have to be figured out once the Integration is in an initial working state, in order to know which permissions are required and which are not.
• Why do we need authentication?

2. Layout

• The RESIZE message is probably not needed. NovaCrate can be dynamically sized, and the parent app can just dictate the height and width to use
• There are some external links in NovaCrate, but I am pretty sure they all open in a new tab. We definitely should make sure this is the case though. Both target="_self" and target="_top" are probably undesired

3. RO-Crate Data Lifecycle

1. Initial Load: This could be any file type that NovaCrate can handle, so .json-ld (as a string or an object), .zip, .eln (as Blob)
2. Partial Sync: Is this necessary? Are you interested in partial entity updates?
3. Final save: Should this be triggered by NovaCrate or by the parent app? We can either...
   3a. Write full crate to parent app when user saves in NovaCrate
   3b. Write full crate to parent app when parent app requests it (saved state or modified state?)

[craquet]

Meeting Notes 10.02.2026

1. Security

IAI hosts their own instance. Can easily put in each other as trusted origins.

2. Layout

Not needed

3. RO-Crate Data Lifecycle

• File and folder creation must be disabled
• Only metadata exchange via postMessage
• NovaCrate can not be used by multiple users in parallel on the same crate
• NovaCrate writes the full crate metadata to the parent page on save

[craquet]

Current implementation challenges:

• Should it be forbidden to delete data entities?
• Should it be forbidden to rename data entities?

(work in progress until next meeting)

[koubaa-hmc]

Hello Christopher, The sentence ‘File and folder creation must be disabled’ in the meeting notes 10.02.2026 indicates that files and folders cannot be added. There are no constraints regarding data entities; they should be deletable and re-namable. Please let me know if I have misunderstood. Best regards Anis

…

On 12. Feb 2026, at 16:18, Christopher Raquet ***@***.***> wrote: craquet left a comment (kit-data-manager/NovaCrate#313) <#313 (comment)> Current implementation challenges: Should it be forbidden to delete data entities? Should it be forbidden to rename data entities? (work in progress until next meeting) — Reply to this email directly, view it on GitHub <#313 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/A3DJFITIWF2COZZS3GTB2O34LSKU7AVCNFSM6AAAAACT2TQ5LCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQOJRGU2TONZWGE>. You are receiving this because you were mentioned.

[craquet]

@koubaa-hmc These were just notes I took during programming, so I don't forget them for the next meeting. We can discuss them then :) but you are right, there is no direct reason to restrict data entities

[craquet]

@koubaa-hmc An initial version of the iframe integration should now be completed. Feel free to try it out in the iframe-integration branch (see #324 ). I also added some documentation about this feature in the docs/iframe-interface.md file (in the aforementioned branch)