# PortaShape Web-Native Surface Patterns

## 1. Declare authority before controls

For every surfaced value, declare the durable authority, submitted proposal, temporary local state, request state, and rendered writer. A control may preview a value without becoming its source of truth.

## 2. Stable shell, replaceable projection

Keep workspace chrome, focus, open state, or local arrangement in a stable Alpine-owned shell. Replace only the narrow server-owned region with htmx.

Use for inspectors, drawers, modals, command palettes, run details, and live panels.

## 3. Deliberately replace disposable state

Replace a complete component when its local menu, draft, or editing state should reset after authoritative server settlement.

Use for rows, cards, inline editors, submitted forms, and state transitions.

## 4. Use native controls as value bridges

Submitted values belong in successful native controls whenever practical. Alpine may enhance the local experience; htmx may submit; the server validates and settles.

## 5. Use URLs for meaningful locations

Search, pagination, selected records, remote tabs, and comparable workspace state should use direct routes or GET state when refresh, sharing, bookmarking, and history matter.

## 6. Model request state as fact

Use htmx request lifecycle, indicators, disabled controls, and explicit jobs rather than duplicating authoritative loading and completion facts in Alpine.

## 7. Use semantic events as contracts

Commands request work; past-tense facts announce outcomes. Define producer, listener, payload, timing, scope, failure behavior, and version.

Examples:

- `mapping-run-requested`
- `mapping-run-completed`
- `surface-preview-applied`
- `destination-validation-failed`

## 8. Isolate rich JavaScript islands

Graph canvases, code editors, charts, and high-frequency visualizations may need dedicated JavaScript. Give each island explicit input bindings, output events, initialization, cleanup, and a stable replacement boundary.

## 9. Preserve only with evidence

Prefer correct boundaries over blanket DOM preservation or morphing. When preserving state, require stable identity and integration tests.

## 10. Treat accessibility and production behavior as contracts

Generated surfaces must define labels, keyboard behavior, focus movement, status announcements, error presentation, direct-route behavior, cleanup, security authority, and test coverage.