hyperapp skeleton docs

src/new/templates/rust/ui/hyperapp-skeleton/.gitignore

@@ -0,0 +1,9 @@
+*/target/
+/target
+pkg/*.wasm
+pkg/ui
+*.swp
+*.swo
+*/wasi_snapshot_preview1.wasm
+*/wit/
+*/process_env

src/new/templates/rust/ui/hyperapp-skeleton/README.md

@@ -3,38 +3,18 @@
 A minimal, well-commented skeleton application for the Hyperware platform using the Hyperapp framework.
 This skeleton provides a starting point for building Hyperware applications with a React/TypeScript frontend and Rust backend.
 
-Either prompt your favorite LLM directly with instructions on how to build your app or add them to `instructions.md`!
+Example prompt (works well with Codex):
 
-Recommended usage:
-- Create a skeleton repo using a kit template:
-  ```bash
-  kit new foo --template hyperapp-skeleton --ui
-  cd foo
-  ```
-- Write a detailed document describing what you want your app to do.
-  Save this in `instructions.md`.
-- Prompt your LLM agent (i.e. Claude Code) with something like:
-  ```
-  ## GOAL
-
-  <One-sentence description of app here>
-
-  ## Instructions
-
-  Read the README.md and follow the Instructions > Create an implementation plan
-  ```
-
-- After creating an implementation plan, clear your LLM agent's context and then prompt it again with something like:
-
-  ```
-  ## GOAL
-
-  <One-sentence description of app here>
+```
+Use `kit new myappname --template hyperapp-skeleton --ui`, (replacing myappname with appropriate app name) to make a template in `/desired_folder`, which you will modify to build the following app:
 
-  ## Instructions
+Insert your app spec here, e.g.:
+Todo List with P2P Sync.
+A collaborative TODO list where items sync between nodes.
 
-  Read the README.md and follow the Instructions > Implement the plan
-  ```
+Write a spec, and then implement it step by step. Use the README.md given in hyperapp-skeleton to find instructions on specific details.
+At the end, I should be able to run `kit bs —hyperapp` and manually test that the app works.
+```
 
 The rest of this document is aimed at *LLMs* not *humans*.
 
@@ -98,6 +78,18 @@ async fn my_endpoint(&self) -> String {
 }
 ```
 
+#### Remote Requests
+All remote requests must use `.expects_response(30)`, where the value 30 sets a 30‑second response timeout.
+```rust
+let req = Request::to(("friend.os", "some-hyperapp", "some-hyperapp", "publisher.os"))
+    .expects_response(30)
+    .blob(LazyLoadBlob {
+        mime: None,
+        bytes: message,
+    })
+    .body(body);
+```
+
 #### Frontend API Calls
 Parameters must be sent as tuples for multi-parameter methods:
 ```typescript
@@ -108,6 +100,14 @@ Parameters must be sent as tuples for multi-parameter methods:
 { "MethodName": [param1, param2] }
 ```
 
+#### Frontend keys in snake_case
+All keys in TypeScript need to stay in snake_case (`node_id`), camelCase (`nodeId`) will break the app!
+```typescript
+export interface StatusSnapshot {
+    node_id: string;
+  }
+```
+
 #### The /our.js Script
 MUST be included in index.html:
 ```html
@@ -120,8 +120,8 @@ Your app's state is automatically persisted based on the `save_config` option:
 - `OnDiff`: Save when state changes (strongly recommended)
 - `Never`: No automatic saves
 - `EveryMessage`: Save after each message (safest; slowest)
-- `EveeyNMessage(u64)`: Save every N messages received
-- `EveeyNSeconds(u64)`: Save every N seconds
+- `EveryNMessage(u64)`: Save every N messages received
+- `EveryNSeconds(u64)`: Save every N seconds
 
 ## Customization Guide
 
@@ -159,18 +159,18 @@ Add system permissions in `pkg/manifest.json`:
 
 These are required to message other local processes.
 They can also be granted so other local processes can message us.
-There is also a `request_networking` field that must be true to send messages over the network p2p.
+
+If sending messages between nodes, set:
+```json
+"request_networking": true,
+```
 
 ### 4. Update Frontend
 
 1. Add types in `ui/src/types/hyperapp-skeleton.ts`
 2. Update store in `ui/src/store/hyperapp-skeleton.ts`
 3. Modify UI in `ui/src/App.tsx`
 
-### 5. Rename as appropriate
-
-Change names throughout from `hyperapp-skeleton` (and variants) as appropriate if user describes app name.
-
 ## Common Issues and Solutions
 
 ### "Failed to deserialize HTTP request"
@@ -187,30 +187,25 @@ Change names throughout from `hyperapp-skeleton` (and variants) as appropriate i
 - Add #[derive(PartialEq)] to structs
 
 ### Import Errors
-- Don't add `hyperware_process_lib` to Cargo.toml
-- Use imports from `hyperprocess_macro`
+- Import the most important structs and functions from `hyperware_process_lib`, e.g. `Request`, `LazyLoadBlob`, `ProcessId`
 
-## Testing Your App
+### manifest.json missing
+- Run `kit b --hyperapp` to generate it
 
-1. Deploy app to a Hyperware node (after building, if requested):
-   ```bash
-   kit start-packages
-   ```
-2. Your app will be automatically installed and available at `http://localhost:8080`
-3. Check the Hyperware homepage for your app icon
+### Naming Restrictions
+- No struct/enum/interface name is allowed to contain digits or the substring "stream", because WIT doesn't allow it
+- No record/variant/enum name is allowed to end with `Request`, `Response`, `RequestWrapper`, `ResponseWrapper`, because TS caller utils are autogenerated with those suffixes
 
 ## Instructions
 
 ### Create an implementation plan
 
-Carefully read the prompt; look carefully at `instructions.md` (if it exists) and in the resources/ directory.
-In particular, note the example applications `resources/example-apps/sign/`, `resources/example-apps/id/`, and `resources/example-apps/file-explorer`. Note that `file-explorer` example contains an `api`, which is generated by the compiler, and not human or LLM written.
+Carefully read the prompt; look carefully at `instructions.md` (if it exists) and in the example-apps directory.
+In particular, note the example applications `example-apps/sign/`, `example-apps/id/`, and `example-apps/file-explorer`. 
+Note that `file-explorer` example contains an `api` folder, which is generated by the compiler, and not human or LLM written.
 `sign` and `id` demonstrate local messaging.
 `file-explorer` demonstrates VFS interactions.
 
-Expand the prompt and/or `instructions.md` into a detailed implementation plan.
-The implementor will be starting from this existing template that exists at `hyperapp-skeleton/` and `ui/`.
-
 Note in particular that bindings for the UI will be generated when the app is built with `kit build --hyperapp`.
 As such, first design and implement the backend; the interface will be generated from the backend; finally design and implement the frontend to consume the interface.
 Subsequent changes to the interface must follow this pattern as well: start in backend, generate interface, finish in frontend
@@ -219,15 +214,9 @@ Do NOT create the API.
 The API is machine generated.
 You create types that end up in the API by defining and using them in functions in the Rust backend "hyperapp"
 
-Do NOT write code: just create a detailed `IMPLEMENTATION_PLAN.md` that will be used by the implementor.
-The implementor will have access to `resources/` but will be working from `IMPLEMENTATION_PLAN.md`, so include all relevant context in the PLAN.
-You can refer the implementor to `resources/` but do not assume the implementor has read them unless you refer them there.
-
 ### Implement the plan
 
-Look carefully at `IMPLEMENTATION_PLAN.md` and in the `resources/` directory, if relevant.
-In particular, note the example applications `resources/example-apps/sign/`, `resources/example-apps/id/`, and `resources/example-apps/file-explorer`.
-Use them if useful.
+Look carefully at `IMPLEMENTATION_PLAN.md` and in the `example-apps/` directory, if relevant.
 
 Work from the existing template that exists at `hyperapp-skeleton/` and `ui/`.
 
@@ -245,5 +234,3 @@ Notice that this all happens within those functions: just take the rust types as
 If you create a GUI for the app you MUST use target/ui/caller-utils.ts for HTTP requests to the backend.
 Do NOT edit this file: it is machine generated.
 Do NOT do `fetch` or other HTTP requests manually to the backend: use the functions in this machine generated interface.
-
-Implement the application described in the `IMPLEMENTATION_PLAN.md`.