---
name: superprez-packaging
description: >-
  Package interactive HTML presentations as Superprez drop-code zips and
  Superengine-compatible static ports. Use when building, repackaging, fixing,
  or updating decks for Superprez upload, GitHub-linked repo push, zip drop-code,
  or html/ docroot. Enforces hosting compatibility; UX (slides, scroll, layout)
  follows user choices — ask before imposing patterns.
---

# Superprez packaging

Package presentations so **Superprez** can `npm ci` → `npm run build` → `npm start` and serve the deck at `/`.

Default stack: **static HTML under `html/`**, Node preview server, nginx in production via Superengine compose. Do **not** use Vite/React/Next unless the user explicitly requires it.

| Resource | Purpose |
|----------|---------|
| [reference.md](reference.md) | Superengine boilerplate templates |
| [deck-html-patterns.md](deck-html-patterns.md) | Hosting rules + optional UX patterns |
| [github-workflow.md](github-workflow.md) | Git-linked repo: bump, commit, push |
| [failures.md](failures.md) | Known failure modes |

Public references only (never assume access to a private repo):

- [Superengine ports catalog](https://software.superengine.tech/superengine/)
- [Superengine docs](https://www.superengine.tech/docs)
- [Port license](https://www.superengine.tech/legal/software-license-agreement-for-ports)

---

---

## What Superprez requires vs what is yours to design

**Superprez only cares that the hosted app works** — it does not mandate a specific look, slide chrome, or navigation style.

| Superprez requires (non-negotiable) | User's creative choice (ask first) |
|-------------------------------------|-------------------------------------|
| Entry at `html/index.html`, assets under `html/` | Visual design, colors, typography, layout |
| `GET /` returns real content (not a redirect stub) | Slide deck vs scroll story vs single-page app vs dashboard |
| Paths resolve from docroot; build + start pass | How users move through content (keys, scroll, clicks, none) |
| Superengine boilerplate (manifest, compose, etc.) | Fixed canvas vs fluid responsive layout |
| Self-hosted fonts (reliability, not aesthetics) | Visible controls vs minimal/hidden UI |
| Version bump + cache-bust on redeploy | Canvas size, animations, interactions |

**Do not impose a default slide-deck UX** unless the user wants one or their existing HTML already uses slides. Preserve their creative intent; only fix what breaks hosting or what they ask you to fix.

When past issues appear (no way to advance, text piling up), **propose** fixes — do not silently replace their UX with the template deck.

---

## Before you start — ask the user

Ask when the answer is not obvious. **UX questions matter** — do not skip them for greenfield decks.

### Packaging (ask if unclear)

| Question | Why |
|----------|-----|
| **Delivery:** zip upload or GitHub repo linked to Superprez? | Git → bump + commit + push; zip → rebuild archive |
| **Deck title + slug** | manifest, cache-bust strings, package name |
| **Starting material:** single HTML, folder of slides, or scratch? | Step 0 vs merge workflow |

### Presentation model (ask for new decks or broken UX)

| Question | Options (examples) |
|----------|-------------------|
| **How should viewers experience it?** | Classic slides · vertical scroll · one immersive page · free-form interactive app |
| **How do they move forward/back?** | Arrow keys · on-screen buttons · scroll/swipe · click hotspots · custom (describe) |
| **Layout on different screen sizes?** | Fixed canvas scaled as one unit · fluid responsive · full-bleed (describe) |
| **Chrome / controls?** | Visible prev/next + counter · minimal · none (keyboard only) · fully custom |

**Defaults when user says "just package it"** and files already exist: **preserve their UX**; only fix hosting paths and boilerplate. Note assumptions in deliverables.

**Defaults for a brand-new deck with no preference:** ask the presentation-model questions above, or offer: *"Classic arrow-key slides, 1280×720 scaled canvas — or describe something different?"*

| Other | Default |
|-------|---------|
| **Fonts** | Self-host under `html/fonts/` |
| **Interactive features** | Ask if charts, maps, forms, video — may need resize hooks |

---

## Workflow

```
Packaging progress:
- [ ] Pre-flight — delivery method, title/slug (ask if unclear)
- [ ] Step 0 — Normalize HTML + assets into html/
- [ ] Step 1 — Add Superengine boilerplate
- [ ] Step 2 — Deck content: preserve user UX; fix only hosting breakers
- [ ] Step 3 — npm ci && npm run icon && npm run build && npm start
- [ ] Step 4 — Zip (if upload path) or prepare git commit (if GitHub path)
- [ ] Step 5 — PASS/FAIL deliverables
- [ ] Step 6 — Bump version; ask user about commit + push (GitHub path)
```

### Step 0 — User gave HTML + assets (most common)

Do this **before** Superengine boilerplate:

1. Create **`html/`** at package root (sibling of `package.json`).
2. Put entry at **`html/index.html`** (rename `deck.html`, `My Slides.html`, etc.).
3. Move **every** referenced asset under **`html/`**, preserving relative paths.
4. Fix all paths so they resolve from `/` when served (no `../` escaping docroot).
5. **Never** leave `index.html` at zip root next to `package.json`.
6. Add cache-bust query strings: `styles.css?v=DECK_SLUG-1.0.0`.
7. **Self-host fonts** — replace any Google Fonts / CDN `<link>` with local `.woff2` under `html/fonts/` (see [deck-html-patterns.md](deck-html-patterns.md) § Fonts).

Anti-patterns (see [failures.md](failures.md)): meta-refresh to `slides/`, multi-page nav, `../public/` paths.

### Step 1 — Superengine boilerplate

Create every file in [reference.md](reference.md). Replace `DECK_*` placeholders.

**Golden rules:**

1. **One docroot:** `html/` everywhere.
2. **Entitlements:** exactly **`port-number` → `host` → `os`**.
3. **Compose ports:** unquoted `      - {{entitlements.port-number}}:80`
4. **Zip root:** flat or one top-level folder — never double-nested.
5. **`package-lock.json` required.**
6. **`npm start`:** `0.0.0.0`, honor `PORT`, serve `html/`.
7. **LF line endings** in JSON/YAML.
8. **No secrets** in repo or zip.
9. **Exclude:** `node_modules`, `dist`, `build`, `.next`, `__MACOSX`, `.DS_Store`.
10. **Zip size:** keep under **100 MB** (compress large assets; exclude junk).

### Step 2 — Deck content (hosting + user's UX intent)

`GET /` must return **meaningful content** the user intended — not a redirect stub or broken shell.

**Always enforce (hosting):**

- One servable `html/index.html` (or one app entry the user designed)
- No meta-refresh / multi-file page navigation to `slides/*.html`
- Asset paths work from `/`
- If merging per-slide sources, combine into one entry file — **how** they navigate inside is the user's choice

**Only enforce UX the user asked for** (or agree to when fixing a reported bug):

- Slide deck → some way to advance (see [deck-html-patterns.md](deck-html-patterns.md) Pattern A)
- Scaled canvas → uniform scale, not broken reflow (Pattern A)
- Scroll story → vertical scroll works; test on narrow viewport
- Custom app → verify **their** stated interactions work

If the user wants full creative freedom, package as-is after hosting fixes and verify **their** acceptance criteria — not a generic slide template.

If sources are `html/slides/*.html`, merge into one entry at build time — do not ship separate-page navigation as the hosted experience.

### Step 3 — Verify locally

```bash
npm ci && npm run icon && npm run build && npm start
```

Then at `http://127.0.0.1:8080/`:

- HTTP 200, intended content visible
- **User's chosen navigation** works (e.g. arrows if slide deck, scroll if scroll story)
- No broken layout at a narrow width **for the layout model they chose**
- Network tab: no 404s

Do **not** claim PASS without evidence.

### Step 4 — Deliver

**Zip upload path:**

```bash
cd /path/to/package-root
zip -r ../DECK_SLUG-DECK_VERSION.zip . \
  -x "*.DS_Store" -x "*__MACOSX*" -x "node_modules/*"
```

**GitHub path:** skip zip — follow [github-workflow.md](github-workflow.md) after Step 5.

### Step 5 — Deliverables

Print file tree, changed files, and PASS/FAIL for:

**Packaging** (FAIL blocks delivery)

- `html/index.html` exists; assets under `html/`
- Zip topology / manifest / compose / legal files
- manifest app-spec 1.2; 3 entitlements; templates order
- `npm run build` exits 0
- Cache-bust query params present
- Fonts self-hosted (no `fonts.googleapis.com` in index)

**Deck UX** (FAIL only if it contradicts **user's stated intent** or they reported it broken)

- Index serves real content (not redirect)
- Agreed navigation/interaction works
- Agreed layout holds on narrow viewport (no unintended overlap)
- Document what was tested and what the user chose

Fix packaging FAILs before delivery. For UX FAILs, **ask** whether to fix or accept before overriding their design.

### Step 6 — After modifications (GitHub-linked decks)

On **every** edit to a Git-linked deck:

1. Bump `manifest.json` `subject.version` + `package.json` `version`
2. Bump all `?v=` cache-bust strings in `html/index.html`
3. Run `npm run build`
4. **Ask the user:** "Commit and push to GitHub to update Superprez live?"

Only commit/push when the user agrees. See [github-workflow.md](github-workflow.md).

For zip-only decks: bump version, rebuild zip, tell user to re-upload.

---

## After upload / redeploy

1. Bump version + cache-bust strings.
2. Push to GitHub **or** re-upload zip.
3. Hard-refresh live URL (private window if cached).

If deck missing from My presentations, see [failures.md](failures.md).

---

## Repackaging an existing project

1. Read `manifest.json`, `compose.yaml.hbs`, `html/index.html`, check for git remote.
2. Fix Step 0 first (docroot, paths, entry file). Fix UX only per user intent or reported bugs.
3. Align boilerplate with [reference.md](reference.md).
4. Re-run Steps 3–6.

Do not reference local-only folders the assistant cannot access.