@bloomscorp/blooms-ai-embed 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,104 @@
 
 All notable changes to `@bloomscorp/blooms-ai-embed`.
 
+## 0.2.0
+
+Twelve new components, and the bundle is now code-split so adopting one does not
+cost you all of them.
+
+Upgrading is a drop-in **unless you branch on `customElements.get()`** or stage
+`dist/` by hand — see *Action if you are upgrading* below.
+
+### Added
+
+- **Twelve new elements.** `<blooms-login>` is no longer the only thing you can
+  embed:
+
+  | | | |
+  |---|---|---|
+  | `<blooms-crawl-insights>` | `<blooms-sitemap-crawl>` | `<blooms-sitemap-crawl-detail>` |
+  | `<blooms-keywords>` | `<blooms-keyword-detail>` | `<blooms-reports>` |
+  | `<blooms-gmc-analytics>` | `<blooms-social-media-calendar>` | `<blooms-smc-day-detail>` |
+  | `<blooms-influencer-dashboard>` | `<blooms-influencer-detail>` | `<blooms-blog-strategy>` |
+
+  Each takes its state through attributes or properties rather than a URL, since
+  a custom element cannot read the host page's address bar: `project-id` on most,
+  plus `crawl-id`, `keyword-id`, `influencer-id`, `strategy-id`, `event-id`,
+  `date-iso` where the component addresses one record. Components that used to
+  navigate now emit a `bloomsnavigate` event describing where they would have
+  gone — your app decides what that means.
+
+  Declared in `HTMLElementTagNameMap`, so TypeScript knows all thirteen tags.
+
+- **`preload(...features)`.** Fetches a component's code before it is needed:
+
+  ```js
+  await BloomsEmbed.preload('crawl-insights', 'keywords');
+  ```
+
+  Optional and never throws — a failed preload just means the chunk is fetched
+  later, when the component is actually mounted.
+
+### Changed
+
+- **The bundle is code-split: one lazily-fetched chunk per component.** Shipping
+  thirteen components eagerly had grown the download to 162 kB gzipped, with the
+  three largest still unconverted — so every host paid for every component to use
+  one. Now:
+
+  | | Transfer (gzipped) |
+  |---|---|
+  | Loader + shared core | **~65 kB** |
+  | …plus one component | ~69 kB |
+  | …plus all thirteen | ~180 kB |
+
+  `dist/blooms-embed.js` is a ~3 kB loader; the components live in sibling
+  `dist/chunk-*.js` files that it imports by relative path on first use.
+
+- **Elements are defined on demand, not at import.** A tag is registered the
+  first time an instance of it appears, and the browser upgrades the element that
+  was already there. Tags in your HTML behave exactly as before and there is
+  nothing to await. One observable difference:
+
+  ```js
+  import { BloomsEmbed } from '@bloomscorp/blooms-ai-embed';
+  customElements.get('blooms-crawl-insights');   // undefined until one is used
+  ```
+
+  Setting a **property** before a component's chunk arrives is safe — the value
+  is applied once the component is defined. Attributes were never affected.
+
+- **Write actions are enabled** for Social Media Calendar, Influencers and Blog
+  Strategy — create, edit, reschedule, delete, and the AI generation steps. They
+  were read-only in `0.1.x`, with controls that rendered and then returned 403.
+
+### Action if you are upgrading
+
+1. **If you bundle the package** (the recommended setup, and what the Electron
+   guide describes) — nothing to do. Webpack, Vite, esbuild and Rollup all follow
+   the dynamic imports and emit their own chunks.
+
+2. **If you stage `dist/` by hand**, copy **all** of it. `chunk-*.js` must sit in
+   the same directory as `blooms-embed.js`. Copying only the entry leaves you with
+   a package that installs cleanly and renders every component as a blank
+   element, with one console error per component as the only clue.
+
+3. **Remove any `customElements.get()` guard** around showing a component. It was
+   reliable in `0.1.x` because every tag was defined at import; it is not now.
+   Place the tag, or call `mount()`, and let the loader do its work.
+
+### Known gaps, stated so they are not surprises
+
+- `<blooms-keyword-detail>`'s Search Console section is **empty when embedded**.
+  The underlying route takes its project id as a query parameter and carries no
+  authorization of its own, and our allowlist pins project ids in the path — so
+  exposing it would have handed every embedded session cross-project Search
+  Console data. The route is being fixed rather than the allowlist widened.
+- Report generation (Crawl Insights) and bulk delete (Reports) are hidden when
+  embedded: their output is delivered to the blooms.ai portal, which a host app
+  cannot reach. Starting a job whose result you cannot collect is worse than not
+  offering it.
+
 ## 0.1.1
 
 Everything here came from the first production Electron integration reporting

package/README.md

@@ -59,11 +59,49 @@ That is the whole integration. Importing the package defines the elements and in
 `<blooms-login>` renders the sign-in form, remembers the session across reloads, and revalidates
 it on the next load.
 
+### Elements in this bundle
+
+| Tag | What it renders | Token ceiling it needs |
+|---|---|---|
+| `<blooms-login>` | Sign-in form, session persistence, precise error states | — |
+| `<blooms-crawl-insights>` | Crawl results: pages crawled, broken links, page issues, missing meta, duplicate titles, health score. Starts crawls and re-scans single URLs. | `crawl-insights` (or `crawl`) |
+| `<blooms-sitemap-crawl>` | Crawl from a sitemap: start a run, watch progress, browse history. | `sitemap` (or `crawl`) |
+| `<blooms-sitemap-crawl-detail>` | One sitemap run in detail. Takes `crawl-id`. | `sitemap` (or `crawl`) |
+| `<blooms-keywords>` | Tracked keywords: rank, volume, difficulty, trend. Adds keywords, triggers a rank sync. | `manager` |
+| `<blooms-keyword-detail>` | One keyword in detail. Takes `keyword-id`. Its Search Console section is empty when embedded — see below. | `manager` |
+| `<blooms-reports>` | Report list and downloads. Generation and bulk delete are hidden when embedded. | `manager` |
+| `<blooms-gmc-analytics>` | Google Merchant Centre overview: feed health, disapprovals, account issues. | `manager` |
+| `<blooms-social-media-calendar>` | Content calendar: month and list views, statuses, attachments, assignees. Create, edit, reschedule, delete. Takes `event-id` to deep-link a drawer. | `social-media-calendar` |
+| `<blooms-smc-day-detail>` | One day of the calendar. Takes `date-iso` (`YYYY-MM-DD`), required. | `social-media-calendar` |
+| `<blooms-influencer-dashboard>` | Tracked influencers with tiers, platforms, latest metrics. Create and edit. | `influencer-management` |
+| `<blooms-influencer-detail>` | One influencer: profile, platforms, snapshots. Takes `influencer-id`. | `influencer-management` |
+| `<blooms-blog-strategy>` | The blog authoring workflow: topic → SEO research → outline → draft → visuals → metadata → review → publish → promotion → performance. Takes `strategy-id` and `step`. | `blog-publishing` |
+
+A `manager` or `owner` ceiling covers all of them, so one token needs no edit as
+you adopt more. The keys above matter only for a deliberately narrow ceiling —
+and Keywords, Reports and GMC are gated on `manager` itself, so a narrow ceiling
+cannot include them without including everything. A ceiling is never a grant: the
+signed-in user's own per-project permissions are evaluated on every request.
+
+Components that would navigate emit `bloomsnavigate` instead of routing — the
+detail is in the Electron guide, and the payload is typed.
+
+**Two deliberate gaps.** `<blooms-keyword-detail>`'s Search Console section is
+empty when embedded: that route takes its project id as a query parameter and has
+no authorization of its own, so exposing it would leak cross-project data — being
+fixed server-side. Report generation and bulk delete are hidden because their
+output is delivered to the blooms.ai portal, which your app cannot reach.
+
+Feature elements render a sign-in prompt until a session exists, so you can place them
+unconditionally. Each takes an optional `project-id`; omit it and the element follows the
+session's active project, so `BloomsEmbed.setProject()` moves it.
+
 Three things worth knowing:
 
-- **`configure()` once, early.** Elements placed in your HTML upgrade the moment the package
-  evaluates, which is before your `configure()` call runs. They wait for it rather than failing,
-  showing a skeleton meanwhile — so a slow `configure()` is a slow first paint, not an error.
+- **`configure()` once, early.** An element placed in your HTML is upgraded when its chunk
+  arrives, which may be before or after your `configure()` call. Either order is fine: it waits
+  for configuration rather than failing, showing a skeleton meanwhile — so a slow `configure()`
+  is a slow first paint, not an error.
 - **`apiBase` is optional** when you load the bundle from blooms.ai, because it defaults to the
   bundle's own origin. When you install from npm the bundle's origin is *your* app, so **pass
   `apiBase` explicitly**.
@@ -79,6 +117,7 @@ Three things worth knowing:
 | `version` | `string` | Bundle version. |
 | `configure` | `(config: BloomsEmbedConfig) => void` | Call first. Throws on a missing token or a token that is not `blm_embed_…`. |
 | `mode` | `() => 'element' \| 'iframe' \| null` | The resolved rendering mode; `null` before `configure()`. |
+| `preload` | `(...features: string[]) => Promise<void>` | Warms a component's lazy chunk before it is used. Optional, never throws. |
 | `manifest` | `() => Promise<EmbedManifest>` | Pre-login bootstrap: project name, enabled features, theme, branding flag, session TTL. |
 | `login` | `({ email, password }) => Promise<EmbedSessionState>` | Programmatic alternative to `<blooms-login>`, for hosts with their own form. |
 | `session` | `() => EmbedSessionState \| null` | The current session, restored from storage by `configure()`. Synchronous. |
@@ -409,6 +448,40 @@ In Electron, that also means: import it in the **renderer**, never in the main p
 
 ---
 
+## Lazy loading
+
+The bundle is code-split: a small loader plus one chunk per component, fetched the first time that
+component is used. A page embedding one component downloads one component (~69 kB gzipped, against
+~180 kB for the full set).
+
+Nothing in your markup changes. A tag in your HTML is defined when its chunk arrives and the
+browser upgrades the element that was already there. You never await anything.
+
+Three things worth knowing:
+
+- **Do not gate your UI on `customElements.get(tag)`.** It returns `undefined` until that
+  component has been used once. Before code splitting it was defined immediately, so a check like
+  this used to pass:
+
+  ```js
+  import { BloomsEmbed } from '@bloomscorp/blooms-ai-embed';
+  if (customElements.get('blooms-keywords')) { /* no longer true up front */ }
+  ```
+
+- **Setting properties early is safe.** `el.projectId = '...'` on an element whose chunk has not
+  arrived is preserved and applied once the component is defined. Attributes were never affected.
+
+- **Warm a chunk if you know what is next:**
+
+  ```js
+  await BloomsEmbed.preload('crawl-insights', 'keywords');
+  ```
+
+If you stage `dist/` by hand instead of importing the package, copy **all** of it — `chunk-*.js`
+must stay beside `blooms-embed.js`, and `media/*.woff2` beside the stylesheet.
+
+---
+
 ## Security notes worth reading once
 
 - The embed token is publishable, but it is not a secret to be careless with: it is what ties