SOURCE / PINNED RELEASE
Made of little things.
Nappakura
- Release
- a75ca0f8b596…
- Author-recorded commit
- 4463126213fa…
- License
- LICENSE
- Author’s source reference
- nostr://npub182jczunncwe0jn6frpqwq3e0qjws7yqqnc3auccqv9nte2dnd63scjm4rf/wss%3A%2F%2Fgit.napplet.soy%2F/n-8db03001b62
Archive hash verified: b448d77b767ae754…. The source-to-build association is the author’s claim; it has not been independently rebuilt.
# Nappakura
A small papercraft editor built as a sandboxed NIP-5D napplet. Create a low-poly model or import an OBJ or
STL, unfold it into paper pieces, edit the pattern, and export a vector PDF at a
known physical scale. No account or network connection is needed for the editor.
## Use
Start the installed project with `soyli dev` and open its printed URL. Stop the
preview with Ctrl+C when finished. See [docs/napplet-space.md](docs/napplet-space.md)
for the workspace and host tooling contract; do not re-scaffold this project.
1. Open an OBJ, ASCII STL, binary STL, or saved `.nappakura` project. The bundled
gem is available without file access. OBJ polygons are triangulated; coincident
vertices are welded and inconsistent winding is repaired when possible.
2. Set **Longest dimension** in millimetres. OBJ/STL units are ambiguous: confirm
the intended finished dimensions yourself. Automatic unfolding respects the
selected paper size; it splits nets instead of silently shrinking them.
3. Drag the model to orbit; Shift-drag/right-drag pans; wheel/pinch zooms. Clicking
a face links the model to its paper piece. Face and edge selectors in **Tools**
provide a keyboard alternative.
4. **Cut / join** changes a seam. Joins that overlap faces or create a cycle are
refused. Seam edits rebuild the net and rearrange pieces. **Unfold again**
replaces manual seams with a new automatic result. Undo restores prior edits.
5. **Move** drags pieces. Tools offers X/Y placement, rotation, and sheet assignment.
**Arrange** repacks pieces without changing their scale. Tabs can switch sides,
change depth/taper, or be hidden. Colliding tabs are shortened or omitted with
a warning. Matching edge numbers, label size and line width are adjustable.
6. Use **Print preview**, then **Export PDF**. Download the result from the host's
Download button (also visible in fullscreen). Print at **100% / Actual size**; the reference bar should measure
20 mm. Off-page and overlapping pieces must be corrected before PDF export.
7. **Save project** exports editable JSON as `.nappakura`. **Save draft** explicitly
saves one small project to scoped host storage. Unsaved edits are session-only.
On compact screens, switch between **3D model**, **2D pattern** and **Tools**.
Below 280 × 280, an enlarge notice preserves your document. Camera buttons and
numeric controls supplement pointer gestures. Native controls work by keyboard.
## Modelling and agent tools
Use the **Vertex / Edge / Polygon** toolbar to select geometry. The modelling toolbar
exposes primitives, transform, extrusion, inset, split, collapse, weld, delete and fill.
The **Move / Rotate / Scale** gizmo operates on the selected centroid: drag coloured
axes for one dimension, squares for two dimensions, and rings to rotate. Shift snaps
to 1 mm / 15° / 0.1×; Escape cancels. Each drag is one undoable edit. Numeric inputs
remain available for exact values and keyboard-only use. Single-vertex scale/rotation
around its own centroid has no effect; use another pivot in the numeric inspector. The canvas and numeric inspector address the same stable
IDs. Undo/redo covers geometry and paper edits. Geometry edits rebuild the net;
finish modelling before arranging seams and sheets.
Supporting shells offer an **Agent tools** panel. Tools remain private until you
allow access. The same validated commands serve manual controls and tools. Browser
WebMCP projection is separately optional; manual editing works without it. This is
an experimental local profile, **not an accepted NAP**. See
[docs/MODELLING.md](docs/MODELLING.md) for units, history, consent, limits and checks.
## Limits
- Up to 2,000 triangles, 8 MiB per imported/exported file, and 64 PDF sheets.
The current host also limits all session files together to 10 MiB.
- OBJ geometry only: materials, texture maps, animation and PDO files are not supported.
- Simple polygon triangulation and conservative automatic unfolding. Non-manifold,
self-intersecting, open or very dense meshes can require preparation in a modeler.
Open surfaces may need a manual fold-direction check. No mesh simplification or
sculpting brush. Numeric vertex, edge and polygon editing is available.
- Automatic arrangement uses a simple shelf packer; it does not optimize paper usage.
A single face larger than the paper still needs a smaller scale or a revised mesh.
- Editable geometry supports up to 6,000 vertices / 2,000 polygons, subject to the
existing 2,000-triangle render/export limit. See the modelling guide for topology restrictions.
- The CPU canvas renderer is intended for small papercraft meshes. Intersecting
surfaces are depth-tested and opaque; geometric unfolding uses actual 3D lengths.
- This version has been tested in Chromium and soyLI. Real iOS/Android devices and
another production host have not been verified.
## Host boundaries
`fs` supplies host-owned file selection, chunked reads and exports. `storage`
provides explicit draft save/restore; `config` provides the optional 3D seam
preference. All are optional, with disabled controls and explanations when absent.
No hard requirements, identity, social data, relay access, direct network, browser
storage or shell implementation. Optional agent tools use the documented local
`soy.webmcp/1` experiment; no network or sandbox permissions are added. App-owned colors stay the same
across host themes. The SDK was updated to 0.34.1 for the shipped NAP-FS helpers.
The single-file artifact is `dist/index.html`. Geometry, import, preview and PDF
logic have no third-party runtime dependencies beyond the host SDK. See
[docs/brief.md](docs/brief.md) for the design contract.
## Development and checks
```sh
pnpm verify # guidance, geometry/PDF tests, types, single-file build
pnpm test:conformance # reference-shell sandbox checks in Chromium
pnpm test:browser # no optional domains: editing and disabled actions
# With the updated soyLI preview running:
NAPPLET_PREVIEW_URL=<printed-url> pnpm test:modelling:browser
NAPPLET_PREVIEW_URL=<printed-url> node tests/gizmo-browser.mjs
soyli check # startup in the actual Soy host
```
For the hosted import/export smoke test, first run `soyli dev`, then use its URL:
```sh
NAPPLET_PREVIEW_URL=http://127.0.0.1:<printed-port>/ pnpm test:browser
```
`test:geometry` creates fixtures under ignored `.napplet-space/geometry-test/`.
Run `pnpm verify` before the browser test. The browser test uses the Playwright
version already installed with conformance. If needed, point
`PLAYWRIGHT_CHROMIUM_EXECUTABLE` at an installed compatible Chromium executable.
[docs/verification.md](docs/verification.md) records observed coverage, skips,
responsive sizes and remaining device/host gaps. Publishing is a separate action.
