Star Wars: a Horizon app for browsing characters and adopting one as an avatar

A Module Federation remote built with @netsapiens/horizon-sdk 0.2.x, registered
into the /apps menu alongside Example CRM and the Pokemon app. Search ~87
characters and droids by name, species, homeworld or allegiance; a card grid
with a detail panel carrying portrait, lineage, affiliations and the BBY/ABY
dates; and one write — Set as my avatar — through horizonContext.api.

Data is akabab/starwars-api: one static JSON document on raw.githubusercontent
.com, which sends CORS headers, holding complete records. So the app makes one
request and has no per-character detail call and no detail-loading state. SWAPI
was the obvious alternative and carries no images at all; the Databank API has
a bigger roster but only name/description on a cold-starting free instance.

The avatar path is the part with real engineering in it. The endpoint requires
a square 1:1 image and these portraits are tall, so the app crops one in a
canvas: horizontally centred, biased toward the top, because a strictly centred
square of a tall portrait frames a torso rather than a face. It fetches the
image to a Blob and crops from that rather than painting a remote URL into the
canvas — a Blob is same-origin, so the canvas cannot be tainted and toBlob
cannot throw, leaving exactly one requirement (CORS on the image host) instead
of two. Displaying a portrait needs none of this, so the page still works where
the upload cannot, and the failure says which of the three causes it was.

Unlike the Pokemon app there is no sprite repository to pull from: Star Wars
portraits are Lucasfilm's stills, hotlinked from Fandom's CDN by every open
dataset, which is why the crop and its CORS caveat exist at all.

Verified against the published SDK: typecheck clean, build clean,
horizon-verify-bundle PASS on all ten required checks.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JnPtsHsXzbApqMpY6k4Pm9

Author: dwang-CXDO

.github/workflows/checks.yml

@@ -0,0 +1,39 @@
+name: Checks
+
+# Typecheck on every push and pull request.
+#
+# tsc is the point of this workflow. The build runs through babel-loader with
+# @babel/preset-typescript, which STRIPS types without checking them — so the
+# bundle compiles regardless of how wrong the types are, and nothing in the
+# deploy path would otherwise notice. The SDK's compile-time guarantees (a
+# mistyped scope tier being a build error, for one) only hold if this runs.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: checks-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck

.github/workflows/codeql.yml

@@ -0,0 +1,37 @@
+name: CodeQL
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - 'main'
+  pull_request:
+    branches:
+      - 'main'
+  schedule:
+    - cron: '0 2 * * 0'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    strategy:
+      matrix:
+        language: ['javascript']
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: '/language:${{ matrix.language }}'

.github/workflows/deploy-pages.yml

@@ -0,0 +1,89 @@
+name: Deploy to GitHub Pages
+
+# Builds the Module Federation remote and publishes dist/ to GitHub Pages, which
+# serves it as a CDN: a Horizon host loads
+#   https://netsapiens.github.io/horizon-starwars-app/remoteEntry.js
+# GitHub Pages sends `Access-Control-Allow-Origin: *`, so cross-origin loading
+# by the host works. The page itself renders nothing standalone (headless remote).
+#
+# Modeled on horizon-sdk-demo's workflow of the same name, minus its zone
+# manifest check (this app has no Playwright suite to keep in step).
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Allow the deploy job to publish to Pages via OIDC.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# One in-flight deploy at a time; don't cancel a running publish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2 # the version guard below diffs against the previous commit
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      # The remote entry URL is stable, so the version field is what tells the
+      # platform to re-verify. Publishing new bytes under an unchanged version
+      # means nothing re-verifies: the platform goes on enforcing the previous
+      # bytes' hash against the new ones at the same URL, every host fails its
+      # integrity check, and the extension silently stops appearing — no verdict,
+      # no finding, nothing in the portal explaining it. Hence a guard, not a
+      # convention. A push that touches only documentation passes untouched.
+      - name: Refuse to ship changed bytes under an unchanged version
+        run: |
+          PREV=$(git show HEAD~1:package.json 2>/dev/null | node -p "try{JSON.parse(require('fs').readFileSync(0,'utf8')).version}catch(e){''}" || echo "")
+          THIS=$(node -p "require('./package.json').version")
+          [ -z "$PREV" ] && exit 0
+          [ "$PREV" != "$THIS" ] && exit 0
+          git diff --quiet HEAD~1 HEAD -- src webpack.config.js package.json package-lock.json && exit 0
+          echo "::error::Bundle inputs changed but the version is still $THIS. Bump it."
+          exit 1
+
+      # babel-loader STRIPS types without checking them, so the bundle builds no
+      # matter how wrong the types are. This is the only gate that reads them.
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Build
+        run: npm run build
+
+      # The same checks the platform runs on submission — fail here, not there.
+      - name: Verify bundle
+        run: npm run verify
+
+      # Stop Jekyll from stripping webpack's _-prefixed files.
+      - name: Disable Jekyll
+        run: touch dist/.nojekyll
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+*.log
+.DS_Store
+.env*

.npmrc

@@ -0,0 +1,2 @@
+# @netsapiens/horizon-sdk is published to npm with public access — no auth needed.
+@netsapiens:registry=https://registry.npmjs.org/

.nvmrc

@@ -0,0 +1 @@
+22.8.0

INSTALL.md

@@ -0,0 +1,129 @@
+# Installing the Star Wars app on a Horizon instance
+
+The bundle is instance-independent — `publicPath: 'auto'`, no hostnames baked
+in — and published once, to GitHub Pages, for every instance. Installing it on
+a portal is two API calls and no files: **register**, then **deploy** (which is
+what verifies it).
+
+## Prerequisites
+
+- Horizon v46+ with SDK support (`NsApi.horizon_extensions` table exists).
+- `*.github.io` in `approved_cdn_origins` (`NsApi.horizon_extension_settings`).
+  It is what `horizon-sdk-demo` loads through, so on most instances this is
+  already true. Failure here is silent in the UI — look for
+  `[HorizonAppsLoader]` in the browser console.
+- Browsers reaching the portal can reach `raw.githubusercontent.com` (the
+  character index) and Fandom's image CDN (the portraits).
+- For the **Set as my avatar** button only: the API-write master capability
+  enabled for SDK apps, and `avatar` absent from `api_write_deny_resources`.
+  Both are platform-global settings; everything else in the app is read-only
+  against public data and needs neither.
+- A token with write scope. `reseller: *` (platform-global) requires a super
+  user; a reseller-scoped token can only create within its own reseller.
+
+## 1. Publish the bundle
+
+Pushing to `main` does this — see the README. Confirm what the platform will
+fetch:
+
+```bash
+curl -sI https://netsapiens.github.io/horizon-starwars-app/remoteEntry.js \
+  | grep -iE 'http/|content-type|access-control-allow-origin'
+# -> 200, application/javascript, access-control-allow-origin: *
+```
+
+## 2. Register the app
+
+Portal **Platform -> UI SDK Management -> Registered Apps -> Add App** is the
+short path — it registers and gives you the **Deploy** button step 3 needs.
+
+The API equivalent (note the `/registry` segment — `POST /ui-extensions` is a
+runtime read surface and returns 405):
+
+```bash
+curl -X POST "https://<PORTAL_FQDN>/ns-api/v2/ui-extensions/registry" \
+  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
+  -d '{
+    "name": "Star Wars",
+    "description": "Star Wars character browser, with avatar adoption",
+    "version": "1.0.0",
+    "remote_entry_url": "https://netsapiens.github.io/horizon-starwars-app/remoteEntry.js",
+    "webpack_module": "horizonStarwars",
+    "enabled": "yes"
+  }'
+```
+
+Required fields are `name`, `remote_entry_url` and `webpack_module`; everything
+else has a default. **Do not send `id`** — the server derives it as the
+kebab-case of `webpack_module` (`horizonStarwars` -> `horizon-starwars`).
+`webpack_module` is unique platform-wide (409 on a duplicate) and immutable
+once registered.
+
+## 3. Deploy the bundle (required — this is what verifies it)
+
+A registered app sits at `verification_status: none`, is filtered out of
+`/ui-extensions?purpose=runtime` before the browser sees it, and renders
+nowhere. One call fetches, verifies, hashes and promotes:
+
+```bash
+curl -X POST "https://<PORTAL_FQDN>/ns-api/v2/ui-extensions/registry/horizon-starwars/deploy?synchronous=yes" \
+  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
+  -d '{ "remote_entry_url": "https://netsapiens.github.io/horizon-starwars-app/remoteEntry.js" }'
+```
+
+or press **Deploy** on the app's row in Registered Apps, which does the same
+thing and picks the next free version itself.
+
+Reading the response:
+
+- `status` — `approved` and `flagged` both load; only `rejected` blocks.
+  A `size-delta` flag on a first submission is expected.
+- `promoted: true` is the bit that matters; `synchronous=yes` adds `landed`,
+  and `landed: false` means "not observed within the poll budget", not failed.
+- `unchanged: true` means the fetched bytes hash to the current pin — a success.
+- `429` is the per-extension submission rate limit. Wait a minute.
+
+## 4. Verify in the portal
+
+Hard-refresh: **Star Wars** appears in the **Apps** menu (deep link:
+`https://<PORTAL_FQDN>/apps/starwars`).
+
+Then click a character and press **Set as my avatar**. Success says so in the
+panel; the top bar shows the new picture on the next page load, because the
+host reads the avatar once per load.
+
+## Updating
+
+Bump `version` in `package.json`, push to `main`, wait for the Pages deploy to
+finish, then deploy again (step 3). Between the publish and the deploy the
+platform still pins the previous hash while the CDN serves new bytes, so keep
+the gap short.
+
+## Appendix: if the portrait cannot be read
+
+The avatar button fetches the portrait's bytes so it can crop them to a square.
+That read — unlike simply displaying the image — needs the image host to allow
+it. Two things can block it, and the panel reports both:
+
+- **The image CDN sends no CORS header** for this origin. The fetch fails with
+  a bare `TypeError`, with the real reason only in the console.
+- **The portal's Content-Security-Policy** restricts `connect-src` or
+  `img-src`.
+
+Either way, putting the images on the portal's own origin removes the question:
+
+```apache
+<Location "/swimages/">
+    ProxyPass "https://static.wikia.nocookie.net/" timeout=30
+    ProxyPassReverse "https://static.wikia.nocookie.net/"
+</Location>
+```
+
+Then rewrite each record's `image` in `src/api/starwarsApi.ts` to that prefix
+as the index is mapped, and rebuild. Needs `proxy_http` and proxy SSL support.
+Consider caching: these are somebody else's images and somebody else's
+bandwidth.
+
+A portal that cannot allow either is still fine for the rest of the app — the
+grid, the search and the detail panel all work, and only the avatar button
+fails, with an explanation.

KIT-GAPS.md

@@ -0,0 +1,50 @@
+# Kit gaps — `horizonContext.ui`
+
+Components this app reached for and did not find, what it used instead, and
+what that cost. Recorded while building, when the reasoning was still live.
+
+**Please share this file** with the Horizon SDK team — it is the input that
+decides what gets added to the host UI kit.
+
+## An image
+
+- **Reached for:** `ui.Image` (a themed `<img>` with object-fit, a loading
+  state and an `onError` fallback)
+- **Used instead:** `<Box component='img' … />` in
+  `src/components/CharacterCard.tsx` and `src/components/CharacterDetail.tsx`
+- **Cost:** the card owns its own broken-image fallback as component state,
+  about 10 lines. No behaviour lost — `Box` is the sanctioned bare primitive
+  and an image carries no theme colours — but every app that shows a picture
+  rewrites this.
+- **Would have been solved by:** `<Image src fallback alt fit='cover' />`.
+
+## A link
+
+- **Reached for:** `ui.Link`, for the Wookieepedia reference on each character
+- **Used instead:** a `Button variant='text'` calling
+  `window.open(url, '_blank', 'noopener,noreferrer')`
+  (`src/components/CharacterDetail.tsx`)
+- **Cost:** it is a button pretending to be a link — no href, so no middle
+  click, no "open in new tab", no status-bar preview, and a screen reader
+  announces the wrong role. The alternative, a hand-rolled `<a>`, would be
+  unthemed and is what RULE 1 exists to prevent.
+- **Would have been solved by:** `<Link href external>` rendering a real
+  anchor in the host's link style.
+
+## A loading placeholder
+
+- **Reached for:** `ui.Skeleton`
+- **Used instead:** a `Typography` line ("Loading the roster...") in
+  `src/pages/CharactersPage.tsx`
+- **Cost:** the grid pops in rather than resolving from a wireframe, so the
+  page jumps on first paint.
+- **Would have been solved by:** `<Skeleton variant='rect' />`, or exposing the
+  wireframe the widget frame already draws.
+
+## Client-side pagination outside a grid
+
+- **Reached for:** the `DatagridTemplate` footer, for a card grid
+- **Used instead:** a `Load more` `Button` raising a visible-count state
+- **Cost:** small — arguably the better interaction for a card wall. Noted
+  because pagination is otherwise only available by adopting the whole grid
+  template.