Building Modules

Three tiers

Every module runs in one of three tiers, chosen by how much power it needs:

• Declarative
  Pure data — no code runs. A sound-change rule pack or a theme palette. Zero risk, instant. The platform's trusted engine does the work.
• Client sandbox
  Your JavaScript runs inside a locked-down iframe (no network, cookies, storage, or DOM access to the host). It talks to LingoCon only through the host SDK. This is what powers reader widgets, visualizers, and studio panels.
• Server
  Heavy/trusted compute via WASM or edge isolates. Planned for a later phase.

Types & where they apply

Pick a type when you create a module. It determines where the module shows up:

The host SDK

A global host object is injected into every client-sandbox module. Render your UI into the #app element and use these methods:

host.ready()                       // call once, when your script has loaded
host.onInit(function (ctx) { ... }) // ctx = { languageSlug, languageId, permissions, theme }
host.request(method, params)        // returns a Promise of data (see below)
host.reportHeight()                 // re-measure after you change the DOM
host.context()                      // the init context, or null before init

The iframe auto-resizes to your content, but call host.reportHeight() after async renders to be safe.

Data methods & permissions

Read a language's data with host.request(). Each method requires a permission that the installer must grant; declare them when you publish.

Requesting a method you didn't declare (or that wasn't granted) returns an error.

Security model

Full example

A complete reader widget that lists the 20 most recent words:

host.onInit(async function (ctx) {
  const root = document.getElementById("app");
  root.textContent = "Loading…";
  try {
    const { entries } = await host.request("getDictionary");
    root.innerHTML = "";
    const h = document.createElement("h3");
    h.textContent = ctx.languageSlug + " · " + entries.length + " words";
    root.appendChild(h);
    const ul = document.createElement("ul");
    entries.slice(0, 20).forEach(function (e) {
      const li = document.createElement("li");
      li.textContent = e.lemma + (e.ipa ? " /" + e.ipa + "/" : "") + " — " + (e.gloss || "");
      ul.appendChild(li);
    });
    root.appendChild(ul);
  } catch (err) {
    root.textContent = "Could not load data.";
  }
  host.reportHeight();
});
host.ready();

Paste this into the playground, grant read:dictionary, and press Run.

Publishing

1. Create a module and choose a type and tier.
2. Prototype and test it in the playground until it works against your data.
3. On the module's edit page, paste your widget code (client-sandbox) or declarative JSON, tick the permissions you use, and publish a version.
4. Add it to a language (account-wide or per-language). For reader widgets and themes, everyone viewing that language's public page sees it.