Back to Nappakura
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.

docs/MODELLING.md
# Modelling and experimental agent tools

## Editor

Create a box, plane or cylinder, or open an existing OBJ/STL/project. Use the
Vertex / Edge / Polygon toolbar to choose a selection mode, and Multi to add to
selection. Click geometry or use the native Selected elements list in Model tools.
The toolbar has one tab stop with Arrow/Home/End navigation and a fallback where
native focusgroup is unavailable. Numeric operations remain usable without a pointer. On narrow touch screens, the
operation toolbar sits in the Tools view, leaving selection and gizmos beside the model.

All coordinates, translation, extrusion and finished dimensions are millimetres.
Rotation uses XYZ degrees; scale uses positive XYZ factors. The default pivot is
the selected centroid; tools can supply another pivot. Extrusion accepts a connected,
coplanar face region. Inset scales a convex face toward its centroid; it is not a
constant-width offset. Split updates every polygon incident to an edge. Collapse
and weld reject invalid topology instead of silently removing faces. Boundary fill
requires one simple loop. Deliberate open surfaces are allowed.

Geometry edits rebuild the triangle mesh, seams and paper arrangement at the new
physical size. Undo restores prior geometry and arrangement. Paper operations keep
geometry intact. V2 .nappakura files preserve editable polygons and stable IDs;
v1 triangle projects remain readable. Older releases cannot read v2. Imported
triangles sharing one plane are grouped into polygons when their boundary is a
simple loop. Renderer triangles and their internal diagonals are never presented
as separate editable faces or cut/fold seams. Legacy projects with those seams
regenerate their net with a visible layout-review notice.

The existing 2,000-triangle limit applies alongside 6,000 vertices, 2,000 polygons,
512 corners per polygon and 1–2,000 mm finished size. IDs, finite coordinates,
degenerate/duplicate faces, winding, non-manifold edges and vertex fans are checked.
Edits that warp a polygon are rejected: explicitly split it into planar faces first.
Extrusion sidewalls remain quads. This does not certify freedom from every surface self-intersection. Imported meshes
that cannot enter the stricter modeller remain usable for their existing unfolding
workflow; modelling errors explain the rejected edit. No brush sculpting, general
Boolean solids, textures or automatic mesh simplification is supplied.

## Transform gizmo

Move/Scale offer X/Y/Z axes and XY/YZ/ZX plane handles. Rotate offers the three
axis rings. Handles nearly aligned with the camera are hidden until the view is
orbited, avoiding unstable movement. Transform coordinates are world axes in mm,
with the selected centroid as pivot. Preview uses the frozen camera and original
coordinates, with the same geometry validator as the numeric/agent command.
Release commits once; Escape, blur, pointer cancellation or lost capture rolls
back. Invalid final geometry cancels the whole drag. Shift snaps move to 1 mm,
rotation to 15°, and scale to 0.1×. Scale stays positive. Rotation wraps at ±180°
per gesture; use repeated gestures or the numeric inspector for larger angles.
Numeric transform inputs offer exact values, alternate pivots and non-drag access.

## Print and assembly checks

Automatic unfolding plans one tab per paired cut edge across the whole net. It
tries both sides and smaller tabs, with corner clearance. Tab ends are tapered to
fit the receiving polygon at each depth, and their folded footprint must be covered
by that polygon. It can change automatic
seams when that removes an obstructed tab. It never changes the model's scale.
Arrange, PDF export and manual seam edits do not silently rewrite seams. Moving,
rotating or changing the sheet of a piece does not change tab ownership.

The editor, `check_printability` tool and PDF exporter share one check. Every
assembly join needs one collision-free tab at least 1 mm deep and two matching
edge numbers. Numbers rotate along the edge and may sit on its tab; their boxes
must fit without overlap, at a font size of at least 2 mm (about 5.7 pt).
Hidden/disabled tabs, disabled or crowded labels, overlaps and off-page pieces
block PDF export with affected edge numbers. Enlarge or simplify tiny geometry,
enable labels/tabs, or revise seams before retrying. Open boundary edges do not
need a matching tab or number.

The PDF preserves physical scale and includes a cut/fold/glue legend and a 20 mm
reference bar. Print at Actual size / 100%, not Fit to page. Pre-fold dashed and
dash-dot edges, then glue grey tabs behind the same-numbered edge. Dry-fit pieces
before closing the model. These are planar layout checks: they do not certify
3D self-intersection, access for the final glue joint, paper thickness or an
assembly sequence for every model. The shelf packer favors predictable placement
over minimum page count.

## Shell and agent access

`src/commands.ts` owns the document revisions, history and validated commands.
`src/tool-definitions.ts` describes 20 task-level tools, including read-only inspection,
printability checks and topic-specific guidance. The UI uses the same command layer.
Mutations require the exact `expectedRevision`; stale edits fail without changing
state. File operations, transform-gizmo drags and live piece drags block concurrent mutations. Invalid
edits roll back. Undo/redo is bounded to 40 checkpoints / 8 MiB.

The optional injected `window.napplet.webmcp` binding is used only when its profile
is `soy.webmcp/1`. Registration never grants access. In the shell's Agent tools panel,
allow internal tools and/or browser agents separately. Unsupported shells keep the
normal UI. The shared shell inspector can exercise tools without an inference key.
A future shell-owned chat can consume the same registry; no chat is implemented here.

Opening a different file/draft/example immediately suspends calls and revokes access.
Agent undo/redo cannot cross that document boundary. Manual history remains available;
crossing the boundary manually revokes access before exposing the restored document.
Tool descriptions and guidance are untrusted task context, never shell permissions.

PDF export uses existing NAP-FS and its separate host-controlled file approval. It
returns metadata when the PDF is ready in the host file panel, not bytes or a public
URL. A user must download the file there. Cancellation prevents later writes but cannot
undo completed writes or dismiss every host file prompt; the shell holds the call slot
until the executor settles. Inspect the file panel before retrying an uncertain export.

## Reference status and checks

Local reference, 2026-11-13. This is not an accepted NAP or a claim of universal
WebMCP compatibility. The shell adapter targets the WebMCP draft at
`56b8e7a74a312c4298858f8211388a536b835339` (`document.modelContext`). Its internal
registry is shared by the website and bundled soyLI preview. In test Chromium the
native API is absent; native registration is contract-tested with a mock, not a real
external browser agent. Publication identity and manifest requirements are unchanged.

Run `pnpm verify`, `pnpm test:conformance`, and `pnpm test:browser`. With the updated
soyLI preview running, run `NAPPLET_PREVIEW_URL=<printed-url> pnpm test:modelling:browser`
for manual creation, consent, tool edits, stale-write refusal, undo/redo, unfolding,
PDF approval/download, fullscreen and small frames. The website runtime has a separate
isolated browser test using this artifact. Tests make no public relay or inference calls.

Conformance currently reports 5 passed / 5 skipped: the unsigned fixture supplies no
manifest evidence, recorded wire evidence or teardown measurement. Real devices,
physical assembly, independent production-shell agent support and exhaustive adversarial
geometry remain unverified. See verification.md for the earlier editor baseline.