# Product

<!-- impeccable:product-schema 1 -->

> **How this file was written.** Impeccable's `init` normally interviews
> the user before writing anything here. This one was written from
> repository evidence instead, during slice 1 and brought up to date at
> the end of each slice since — most recently slice 3: the design
> (`docs/superpowers/specs/2026-09-07-slides-design.md`, revision 1), the
> plans (`docs/superpowers/plans/2026-09-07-slice-1-live.md`,
> `2026-09-07-slice-2-editor.md` and `2026-09-08-slice-3-export.md`),
> `AGENTS.md`, and the shipped code in `internal/slides/` and
> `fixtures/`. Facts traceable to a spec
> ruling or to code are cited. Anything that is a reading rather than a
> citation is marked **[inferred — confirm]** and should be corrected
> rather than trusted.

## Platform

web

## Users

**Primary: a member of one team, making and giving a talk.** The instance
boundary *is* the team — one deployed instance per team, not one
multi-tenant app with teams inside it (spec §0.2, suite rulings 1 and 5).
Sharing is therefore membership plus a link capability, not a permission
matrix.

**Secondary: an agent, driving a deck on a person's behalf.** Not a
metaphor and not a later feature — it was the only way to build a deck
before the editor existed, and it is still a peer of it: an agent's ops
and a person's keystrokes land in one document, in one order. An agent is
its own principal,
`<name>~<operator email>`, minted by a signed-in person and named in every
write it makes (spec §1 ruling 7, §7.1). It never borrows a person's
session, and the API never reads a session cookie.

**Third: someone holding a share link**, who has no account and gets a
read-only deck (spec §5). If a talk is live, that same link offers "follow
the presenter" (§3.4).

Access today is a magic link gated by `SLIDES_ALLOWED_ADDRESSES`
(`internal/slides/auth.go`) — a per-instance allowlist, exactly Docs'
shape, chosen because the suite home that will own identity is a skeleton
(spec §1 ruling 8). Guest grants and edit links wait on that home (§5, §9).

**[inferred — confirm]** The team is assumed small enough that an address
allowlist is the right admission mechanism. Nothing in the repo states a
target team size.

## Product Purpose

Slides is a **presentation editor** for the Oficina suite: a deck that
looks like a Keynote deck on a desktop, reads like a document on a phone,
is presented from a laptop and driven from a phone, exports to PDF, and is
driveable by an agent through the same operations a person has (spec
preamble).

Success is a deck that is genuinely the same deck everywhere it is seen —
one block tree, rendered for a viewport rather than authored twice (§0.1).
A phone does not get a cut-down deck; it gets the same deck reflowed.

## Positioning

Three things a neighbouring presentation tool could not copy without
rebuilding its foundations:

1. **One tree, one renderer, no second layout.** The layout modes are two
   placements of the same blocks, and the phone layer is entries in the
   same tree (§2.3, §2.5). `internal/slides/render` is the only code that
   turns a slide into HTML, and it serves the viewer, the presenter view,
   the remote, and the editor's stage and thumbnails (§4.1) — the browser
   fetches that HTML rather than drawing its own. A product with a mobile
   view bolted on cannot make that claim afterwards, and neither can one
   whose editor renders slides a second time in JavaScript.
2. **An agent is a first-class author, badged as itself.** Every write
   records `person:<id>` or `agent:<id>` (`DeckUpdate.Actor`,
   `internal/slides/models.go`; spec §6.2), and the agent's writes are
   attributed to the agent with its operator named, never laundered into
   the person's name. Slides is the first Oficina app to build that
   surface (§0.2).
3. **Presenting is a server-side session, so the room is one system.** The
   presenter view, the projector, the phone remote and every audience
   follower read and write one record (§3.4, `internal/slides/
   presentation.go`). A phone remote is not possible at all in a design
   where presenting is just a viewer with no session, which is the
   rejected alternative recorded in §1 ruling 5.

**What is not shipped and must not be described as though it were:**
comments, version history, charts from Sheets, video and embeds, an MCP
adapter, aspect ratios other than 16:9. §9 gives each a trigger rather
than a date. And **the first deployment has no object store bound**, so
image upload — which is built, and works against a bucket or a
directory — answers `503` there and says so on the page, and an exported
PDF is held in the instance's own memory for an hour instead of going to
a bucket.

## Operating Context

- **One Go binary per instance**, `CGO_ENABLED=0`, cross-compiled to
  `linux/arm64`, on the CARLOS platform, at `slides.oficina.works` for the
  first team (spec §6.3, `Makefile`).
- **The deck is a Yjs document held by a Rust `yrs` core compiled to wasm
  and run under wazero** (spec §1 ruling 3; `core/`,
  `internal/slides/core`). The Go side persists updates in SQLite, asks
  the core for a JSON view, and renders that view. This is Docs' pattern,
  adopted rather than reinvented.
- **Routes shipped today** (`internal/slides/app.go`): sign-in and the
  deck list, `/decks/new`, `/d/{sqid}` and its notes, settings, share and
  delete pages; the editor at `/d/{sqid}/edit` with its slide HTML twin,
  its `.svg` thumbnail twin, its update log, stream and presence, and its
  upload, register and asset routes; `/d/{sqid}/export`, the job's status
  page under it and the `.pdf` beside that; `/s/{token}` for a share link; `/p/{session}` and its notes,
  stream, remote and command; `/r/{code}` to pair a phone. The share,
  present and remote routes sit outside the session group on purpose —
  the projector, the phone and the audience each carry their own
  capability and have no session at all.
- **The browser holds a Yjs document too.** The editor's bundle is
  committed, hashed, and built by hand from `fixtures/`
  (`node build-bundles.mjs`); the app builds nothing at run time and CI
  builds nothing for it. `fixtures/` is also a second implementation of
  the operation vocabulary, held to the Rust one by generated vectors
  (spec §2.8) — an operation changes on both sides or on neither.
- **Local development** is `./scripts/run-dev.sh`: `localhost:8091`, a
  scratch SQLite database that starts empty every run, magic links logged
  to the terminal rather than mailed.
- **The scriptless floor is a product requirement, not a fallback** (spec
  §8). Signing in, listing, creating, viewing, presenting, reading notes,
  managing sharing and using the remote all work with JavaScript off; each
  remote button is a form that POSTs and redirects. The editor is the one
  stated exception, and it says so in a `<noscript>` that links the
  viewer — a boundary declared in the spec before it was built, not
  discovered afterwards.
- **Work happens on a worktree branch and reaches `main` only by squash
  merge**, after review and with the gate green. The review record is an
  amadan branch discussion, not a GitHub PR — this repo is hosted on an
  amadan hub (`AGENTS.md`).

## Capabilities and Constraints

**Shipped in slice 1:** magic-link sign-in with an admission allowlist and
a `users` row per person; deck list, create, settings, delete, three
sharing rungs; the Rust core with the deck schema, the operation set and
the JSON view; the HTML renderer with eleven block types, seven flow
templates, the canvas frame, the phone layer and six themes; the paged
viewer and the notes page; read-only share links, hashed and revocable;
presentation sessions with the fullscreen surface, presenter view, phone
remote and audience follow; the drive API for creating and driving a deck.

**Shipped in slice 2:** the browser editor at `/d/{sqid}/edit` — slide
strip, stage, inspector for the deck, the slide and the selected block,
text edited in place, canvas drag and resize with snapping, the
desktop/phone switcher whose phone-view edits become overrides rather than
changes everyone sees, undo scoped to the person who made the change, and
presence. Under it: the live-sync wire (an update log served by cursor, an
SSE stream of advisory seqs and whole presence sets, periodic snapshots so
opening a long-lived deck is not a full replay), image upload
browser-to-bucket with SVG sanitising and a deck-scoped check on every
byte served, and the JS half of the operation vocabulary with the vectors
that hold it to the Rust one.

**Shipped in slice 3:** the layout engine (`internal/slides/layout`),
which measures a slide into a paint list with the twelve Liberation faces
embedded in the binary and served to every slide surface; the SVG
serialiser over that paint list, and a thumbnail route on all four
capabilities; and PDF export — `krilla` compiled to wasm32 and hosted
under wazero beside the CRDT core (`core/pdf`,
`internal/slides/pdfcore`), driven by a rastrillo job whose status page
polls itself and works with scripts off: one 16:9 page per slide, the
speaker notes as pages of their own when they are asked for, the text as
embedded subset glyphs, the images inlined. The API twins are
`POST /api/v1/decks/{sqid}/export` and its two GETs.

**Deliberately not built yet** (spec §9): charts from Sheets, video and
embeds, an MCP adapter, 4:3 and custom aspect ratios, comments, and
version history. Each has a named trigger in §9 rather than a date.

**Binding technical constraints:**

- **A slide is one block tree, rendered many ways** (§0.1). Nothing that
  matters to what a reader sees may live outside the tree.
- **Every write names its real actor**, `person:<id>` or `agent:<id>`
  (§6.2). An agent's write names the agent and its operator, never the
  person (suite ruling 9, plus Paul's 2026-09-07 ruling that agents drive
  every Oficina app as their own identified principal).
- **Not-found and not-yours both answer 404, never 403**
  (`internal/slides/decks.go`), so a stranger holding a sqid cannot learn
  whether it is real.
- **Only the SHA-256 of a share link is stored**, so the URL is shown
  exactly once and the page says so at that moment (`share.go`, §5).
- **Every user-visible string is a catalog key** resolved through
  `rastrillo.T` (`internal/slides/locales/en.toml`, 339 keys today).
  Twelve base locales are the suite target; one, `en`, exists. A
  hardcoded English string is a bug — including in the editor's
  JavaScript, which reads its strings off `data-text-*` attributes the
  template renders from the catalog. Deck titles and timestamps are data,
  not authored copy, and are correctly not keys.
- **The document is the log, and presence is not in it.** Every write is
  a row with an actor; a snapshot is a shortcut and never the truth.
  Presence lives in memory, reaches no log, is in no snapshot, and is
  gone when the process restarts (spec §3.3).
- **The browser is not a second renderer.** The editor's stage shows the
  server's HTML for the current slide and rebinds after a structural
  change; building slide markup in JavaScript would recreate exactly the
  divergence §0.1 exists to prevent.
- **`href` is stored as the one-key map `{"href": url}` and the marks are
  named `b`, `i`, `c`, `h`, `href`** (§1 ruling 12, §2.6). Forced by
  y-prosemirror, which has no hook to map mark names to attribute names
  and deletes a text node when a read throws — so the wrong shape loses
  the words, not just the link.
- **Markup is the bare `rst-*` attribute grammar**, never `class="rst-*"`;
  this app's own attributes are `slides-*`.
- **Themes are a built-in set of token bundles**, six of them (`paper`,
  `ink`, `sunset`, `forest`, `slate`, `candy` —
  `internal/slides/render/themes.go`). A deck may override accent and the
  two typefaces; there are no per-block fonts, which §1 ruling 9 calls the
  fastest route to an ugly deck.
- **`CGO_ENABLED=0` everywhere**, and the committed wasm artifact must
  match a fresh build or the gate fails.

## Brand Commitments

- **Name:** Slides, in the `oficina` namespace at
  `amadan.net/oficina/slides`, hosted at `slides.oficina.works` for the
  first team (§1 ruling 11). English, not Spanish — the suite names
  generic apps in English.
- **The design system is rastrillo's**, with estilo
  (`amadan.net/oficina/estilo`) as the suite variant. Vendor tokens rather
  than copying files by hand.
- **A slide is not themed chrome.** The deck carries its own theme tokens
  as CSS custom properties on each `<section slides-slide>`
  (`render/render.go`); the app's chrome follows the design system and the
  slide does not follow the reader's preferences. **[inferred — confirm]**
  The spec does not spell this out for Slides the way Docs' §10.2 does for
  the page canvas; it is the reading the renderer implements.
- **The empty state is a designed screen, not a blank page**, and says
  what the screen is for: "A deck is a set of slides you write, present
  and share. Start one and it will show up here."
  (`slides.decks.empty.body`).
- **Voice, as evidenced by the shipped catalog:** plain, unhedged, second
  person, no exclamation marks, no product cheer. Headings carry no full
  stop ("No decks yet"); errors state what happened and what helps ("That
  link has expired or was already used. Enter your email below for a new
  one."); a warning goes in front of the button rather than in a help page
  ("Copy this now — it is not shown again").
- **What does not exist and must not be invented:** no customers, no
  testimonials, no benchmarks, no pricing, no usage numbers, no launch
  date, no press. There is one instance and it is not live yet.

## Evidence on Hand

- **Spec:** `docs/superpowers/specs/2026-09-07-slides-design.md`, revision
  1, drafted 2026-09-07 from a brainstorm with Paul the same day. It is
  **unreviewed**: §12 records that the review pass is the first item after
  slice 1 ships, so the reviewer has a running instance rather than a
  document. Treat its rulings as settled and its prose as unaudited. One
  amendment has landed since: ruling 12 and the rewritten §2.6, added
  during slice 2 when the fixtures proved the old `href` shape did not
  survive y-prosemirror.
- **Plans:** `docs/superpowers/plans/2026-09-07-slice-1-live.md` (eight
  tasks) and `2026-09-07-slice-2-editor.md` (seven), one slice each.
- **Consumed rulings:** the suite sharing doctrine (`oficina/suite`,
  revision 8) by number — 1, 4, 5, 6, 9, 12, 15 — never restated here
  (§0.2). Docs' live-sync design is adopted as written for slice 2 (§3.3).
- **API reference:** `docs/api.md`, every endpoint and every operation
  with an example, written for a person and an agent both.
- **The export, end to end:** `internal/slidestest/export_test.go` walks
  the button, the job, the polled fragment, the SSE stream and the file,
  and asserts the first heading is extractable with `pdftotext` when the
  machine has one (visibly skipped when it does not).
  `internal/slides/export_test.go` does the same at the pipeline's own
  level, recovering every heading from the PDF's glyph runs through each
  font's ToUnicode CMap.
- **Sample content:** `internal/slides/sample.go` seeds one deck on first
  sign-in, covering each flow template, a canvas slide and a phone-reflow
  slide — which is also the fastest way to see what the renderer does.
- **The contract between the two implementations:** `fixtures/data/*.json`
  are operation batches, `fixtures/vectors/` is what the JS side makes of
  them, and `internal/slides/core/vectors_test.go` requires the Rust core
  to agree. Five vectors between them exercise every operation in §7.2.
- **The gate:** `.amadan/ci.d/10-gate`, run by CI and by hand, and
  `.amadan/README.md` for what it needs. Since slice 2 it also runs the JS
  toolchain — `npm ci`, `node --test`, the vectors regenerated and the
  bundle rebuilt, both diffed against what is committed — which is what
  makes the two claims above checkable rather than remembered.
- **The browser drive:** `internal/slidestest/browser_test.go` walks the
  editor in a real Chromium and fails on any console error, failed request
  or JS value that reached the screen. It is deliberately outside the
  gate: this project's sandbox will not start a Chromium, and a gate that
  ran it would report "could not see" as green.

## Product Principles

1. **State the degradation rather than let it be discovered.** The spec
   refuses to claim pixel identity between the browser and the PDF and
   says where they may differ (§0.3, §4.2); the share page says the URL
   will not be shown again at the moment it is shown; the editor's image
   field, on an instance with no object store, says so on the page instead
   of waiting for somebody to choose a file and hit a 503.
2. **One tree, one renderer.** Any second representation of a deck — a
   mobile layout, a print document, an editor's own idea of a slide — is
   a design mistake before it is a maintenance cost, because the two will
   diverge and the divergence will reach a reader.
3. **A capability is a capability, and nothing more.** A share link never
   edits (suite ruling 15). An edit link does not exist, because an edit
   capability is a sign-in that mints a guest grant, and that waits on the
   home (§5).
4. **An agent is a principal, never a costume.** It has its own token, its
   own name, its own revocation, and its own badge in the activity list
   (§7.1). The alternative — an agent borrowing a person's session — is
   recorded as rejected, not overlooked.
5. **The scriptless floor is the floor, not a fallback.** A screen that
   only works with JavaScript is a screen that has not been finished
   (§8).
6. **A string a person can read is a catalog key.** Localisation is a
   structural property of the app, not a phase.

## Accessibility & Inclusion

**WCAG 2.2 AA, no exemptions** (spec §8, restated in `AGENTS.md`). Four
requirements bind concrete decisions here:

- **24×24 minimum target size**, which the phone remote's buttons are
  sized for — it is a control someone uses in the dark, one-handed, while
  talking.
- **320px reflow.** The one allowance is estilo's: the canvas stage may
  scroll inside its own region in the editor (§8). Nothing in the viewer
  uses it. Below 1100px the editor's three panes stack — the strip
  becomes a horizontal filmstrip and the inspector a `<details>` at the
  foot — rather than scrolling the page sideways.
- **Canvas resize handles are pointer-only, and the keyboard has a real
  equivalent** rather than a smaller version of the same thing: the
  selected block's overlay is focusable and named, arrows nudge, Shift
  nudges further, Alt resizes, and the inspector's Left/Top/Width/Height
  fields do it by number.
- **Colour never carries meaning alone**, so a deck's sharing rung shows
  a text label beside its tone and never a bare colour.
- **`alt` on every image.** The model makes it structural rather than
  advisory: `alt` is a required prop on an `image` block and may be empty
  only when `decorative` is true (§2.4).

The phone is not a degraded case. Reflow for flow slides and scale-to-fit
for canvas slides, with a per-slide switch to reflow a canvas slide in
reading order (§1 ruling 2), exists so that reading a deck on a phone is a
supported way to read it.

Twelve base locales are the target set; today exactly one exists (`en`).
That is a commitment, not a shipped state, and this file should not be read
as though eleven more catalogs are sitting in the repo.