# PortaShape Web-Native Runtime Library

## Placement within the product

The uploaded Alpine.js + htmx repository becomes the **PortaShape Web-Native Runtime Library**.

It is not a separate product and it is not the definition of PortaShape’s entire frontend. It is a reusable implementation, architecture, onboarding, and showcase library for one important target: web-native PortaShape control surfaces built from server-rendered HTML plus focused local interaction.

The source corpus is preserved under:

```text
libraries/web-native-runtime/reference/
```

A product-facing wrapper and pattern summary sit one level above the preserved source.

## Why this library belongs in PortaShape

The library’s central architecture mirrors PortaShape’s own conceptual requirements:

- one authoritative owner per state value;
- one intentional writer per DOM boundary;
- server authority for durable truth;
- URLs for navigable state;
- native controls for submitted values;
- htmx for HTTP interaction and targeted server HTML installation;
- Alpine.js for disposable browser-local interaction;
- semantic events for cross-boundary contracts;
- deliberate lifecycle, cleanup, security, accessibility, and production behavior.

PortaShape generalizes these from browser implementation advice into system-model metadata. The runtime library then demonstrates how those contracts can be rendered in a practical web stack.

## Product role

The library supports four PortaShape needs.

### 1. Reference renderer

It provides patterns for rendering generated surfaces with progressive enhancement, narrow server-updated regions, local interaction state, and accessible native controls.

### 2. Component contract library

Its stable-shell, replaceable-interior, disposable-component, event-handshake, and isolated-island patterns become reusable PortaShape surface primitives.

### 3. Contributor onboarding

Its twelve-day curriculum teaches the implementation discipline needed to build PortaShape panels and generated tools without creating duplicate state or competing DOM writers.

### 4. Showcase and pattern bank

Its example-page catalog supplies candidate demonstrations for forms, validation, search, lifecycle, events, multi-region updates, operations, and advanced composite workflows.

## Canonical PortaShape surface patterns

### Local control

Use a local reactive component when the value is immediate, disposable, and browser-local. The control may propose or preview a system value but does not silently become its authority.

### Server projection

Use a server-rendered fragment when the region is an authoritative representation of durable system state.

### Stable shell with live interior

Keep local chrome, focus, visibility, or workspace arrangement stable while refreshing a narrow server-owned projection inside it.

This pattern fits inspectors, drawers, modals, command palettes, detail panes, run consoles, and live dashboards.

### Replaceable component with disposable behavior

Replace the whole component when local interaction should intentionally reset after a server-settled operation.

This fits inline editors, rows, cards, submitted forms, and result states.

### Semantic event handshake

Use named domain events when one owner requests action from another or announces a completed fact. Event definitions should become part of the surface artifact and system model.

### Isolated JavaScript island

Use an explicit island for charts, mapping canvases, code editors, graph layout, drag systems, or high-frequency rendering. The island has clear initialization, cleanup, value bindings, and event contracts.

## Documentation structure

The preserved library includes:

- repository orientation and boot guidance;
- a master index;
- an extensive showcase idea bank;
- four companion architecture guides;
- a twelve-day onboarding curriculum;
- a single-file combined curriculum;
- a source reconciliation and claim audit;
- a machine-readable manifest.

The original relative layout is preserved so its internal links remain usable.

## Version and compatibility posture

The preserved material identifies its verified baseline as Alpine.js 3.15.12 and htmx 2.0.10 / stable 2.x on July 19, 2026, with htmx 4 treated as a version-gated prerelease line in that corpus.

Within PortaShape, the library manifest—not the product canon—owns these implementation version claims. Future revisions should update the library independently while preserving the product-level contracts.

## From training corpus to PortaShape library

The library should gradually gain PortaShape-native packages:

- control renderer definitions;
- surface pattern `.posh` files;
- event-contract schemas;
- accessible component templates;
- test matrices and validators;
- generated example applications;
- adapter examples for server frameworks;
- version compatibility metadata;
- mappings between model element types and web controls.

## What remains framework-neutral

PortaShape’s system model, `.posh` format, mapping engine, validation, provenance, and execution model must remain independent of Alpine.js and htmx. Other renderers can implement the same contracts with different technologies.

The web-native library is valuable because it demonstrates disciplined composition, not because PortaShape requires one frontend stack forever.