Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion assets/MaterialDesignIcons-LICENSE.txt
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
Material Design Icons in Grimoire's Terminess

The 84 icons in assets/TerminessNerdFontMono-Regular.ttf and -Bold.ttf, the code points from
The 86 icons in assets/TerminessNerdFontMono-Regular.ttf and -Bold.ttf, the code points from
U+F0001 to U+F1AF0 that assets/terminess-keep.txt lists (the icons the app draws, on its tools,
buttons and sheets and as the clefs of music paper, and those its next version plans), are Material
Design Icons by Pictogrammers (https://pictogrammers.com/library/mdi/); 52 of them were drawn by
Expand Down
2 changes: 1 addition & 1 deletion assets/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ EOF
Fonts 3.4.0, its Terminess Nerd Font Mono, a patched build of Terminus TTF 4.49.3; SIL Open Font
License 1.1, see `Terminess-OFL-1.1.txt`), cut down to Terminus's text glyphs and the Material
Design icons Grimoire draws or plans: exactly the code points `terminess-keep.txt` lists, 1,197
text and 85 icons. That is about 0.43 MB a weight instead of 2.67 MB. The icons are Material Design
text and 87 icons. That is about 0.43 MB a weight instead of 2.67 MB. The icons are Material Design
Icons by Pictogrammers under the Apache License 2.0 (`MaterialDesignIcons-LICENSE.txt`, which says
where they come from, and `MaterialDesignIcons-Apache-2.0.txt`); the release ships both notices
beside the OFL text, and the share pages serve all three, with the Gothic fonts' OFL texts, as
Expand Down
Binary file modified assets/TerminessNerdFontMono-Bold.ttf
Binary file not shown.
Binary file modified assets/TerminessNerdFontMono-Regular.ttf
Binary file not shown.
6 changes: 4 additions & 2 deletions assets/terminess-keep.txt
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,7 @@ U+2E2C
# the replacement character
U+FFFD

# Icons: 84 code points
# Icons: 86 code points
# Icons: the app's icons (rust/src/ui.rs, the icon table)
U+F064F # md-lead_pencil: the Pencil tool
U+F0CB6 # md-pencil_outline: the Mechanical pencil tool
Expand Down Expand Up @@ -224,6 +224,8 @@ U+F0455 # md-rename_box: Rename
U+F0252 # md-folder_move: moving to a folder
U+F0257 # md-folder_plus: a new folder
U+F01DA # md-download: downloads and exports
U+F00EC # md-calculator: the calculator widget
U+F03D7 # md-package_variant_closed: Packages
U+F0652 # md-marker: the Highlighter tool
U+F00E2 # md-broom: clearing a page
U+F00DF # md-brightness_6: the front light
Expand All @@ -244,7 +246,7 @@ U+F018F # md-content_copy: Copy
U+F0339 # md-link_variant: links
U+F0119 # md-cast_connected: Live view
U+F0297 # md-gamepad_variant: controllers and keys
U+F06B0 # md-update: Updates
U+F06B0 # md-update: Updates and Update all
U+F0150 # md-clock_outline: the clock and battery corner
U+F0349 # md-magnify: the Index: Go to page or name
U+F0208 # md-eye: showing or hiding link areas
Expand Down
147 changes: 147 additions & 0 deletions docs/FORMAT.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,11 @@ root/backlinks.ini links between notebooks, turned around (
root/graph-index.ini every notebook's pages, names and links, for the Graph (2.0.0-beta.2; a cache: Library index)
root/graph-all.ini the Graph of all notebooks' layout (2.0.0-beta.2; a cache: Library index)
root/graph-omit.ini folders left out of the Graph of all notebooks (2.0.0-beta.2; Library index)
root/widgets.ini the open widget windows' places and sizes (2.2, issue #200; Widgets)
root/packages/index.json the installed widget packages (2.2, issue #200; Widget packages)
root/packages/widgets/<id>/package.yaml a widget package's manifest and files (2.2, issue #200; Widget packages)
root/packages/widgets/<id>/state/settings.json the values of a package's declared settings, written by the host (2.2; Widget packages)
root/packages/widgets/<id>.previous/ the version an update replaced, for a rollback (2.2, issue #200; Widget packages)
root/clipboard.qpg the lasso's clipboard: what Copy or Cut took (2.0.0-beta.2; The clipboard)
root/shortcuts.ini keyboard and controller mappings the owner edits (2.0; settings.ini)
root/controller.ini controller buttons learned in Settings (2.0; settings.ini)
Expand Down Expand Up @@ -1571,6 +1576,148 @@ critical on purpose.
every link is kept exactly, `index` included. A paste that would pass 64 links on the page or 4000 in the notebook, or carries
links while links.ini cannot be written, is refused whole.

## `widgets.ini` (2.2, issue #200)

The editor's open widgets, one line each: an installed package's id (`com.example.timer`). A line
is the widget's id, an `=`, and seven comma-separated numbers: x, y, width, height, minimized (0
or 1), z-order, and a reserved flag (written as 0). Coordinates are screen pixels, as the panel's
are. A closed widget has no line. Unknown ids and malformed lines are skipped. The file is at most
64 KiB, written atomically.

```
# Grimoire widget layout. One line per open widget:
# id=x,y,w,h,minimized,z
com.example.timer=1416,28,220,160,0,0,0
com.grimoire.calculator=1416,270,340,560,0,1,0
```

## Widget packages (2.2, issue #200)

Settings → Packages → Widgets installs a widget from a GitHub repository (`user/repo`) or an
HTTPS `.yaml` address; the Widgets popup's **Manage widgets...** row opens the same page.
[WIDGETS.md](WIDGETS.md) is the developer's guide to the manifest, the artifact and publishing.
The manifest is `package.yaml`; unknown keys are ignored. An install is refused before anything is
written if the manifest is invalid, the platform does not match, or the artifact does not match its
size and SHA-256. The artifact is one file under the package's folder; it cannot be `package.yaml`
or anything under `state/`, which belongs to the host and the widget's saved data.

```yaml
name: Timer
id: com.example.timer # lowercase letters, digits, dots and hyphens
version: 1.0.0 # semantic version (a -prerelease suffix is allowed)
type: widget
author: Jane Doe
description: A small timer widget.
license: MIT # optional; the install page asks you to agree to it first
license_url: https://example.org/timer/LICENSE # optional; without it, the repository's LICENSE,
# LICENSE.md, LICENSE.txt, COPYING or COPYING.md is tried
min_grimoire_version: 2.1.0 # optional
platforms: [all] # or kindle-scribe-2022, kindle-scribe-2024
repository: https://example.org/timer
capabilities: [editor:overlay, storage:widget-local]
settings: # optional; a Settings... page of up to 32 rows
- key: show_seconds # lowercase letters, digits, . - _
label: Show seconds
type: toggle # or choice
default: true
- key: layout
label: Layout
type: choice
default: compact
choices: [compact, large]
artifact:
path: timer.bin
sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
size: 4
releases: # optional per-version artifacts
- version: 1.0.0
url: https://example.org/timer/1.0.0/timer.bin
sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
spec:
runtime: wasm # the only runtime; widget code is a WebAssembly module
entry: _start # ignored by the host; `widget_draw` and `widget_tap` are the exports it calls
icon: timer # a Grimoire icon (calculator, clock, timer, music, notebook, pdf, image, ...);
# unknown or omitted: the widget grid
minimizable: true
size:
mode: fixed # or resizable
default: [220, 160]
min: [160, 120] # resizable only
max: [600, 600] # resizable only
```

An omitted `platforms` means every supported device; an explicit empty list is refused. A device's
platform is `GRIMOIRE_WIDGET_PLATFORM` when set, otherwise the Kindle model in
`/proc/device-tree/model`. The known values are `all`, `kindle-scribe-2022` and
`kindle-scribe-2024`. The artifact is at most 32 MiB; at most 64 packages are installed. A manifest
is at most 256 KiB.

`packages/index.json` lists what is installed, and is written atomically after the package's files
are complete:

```json
{
"version": 1,
"packages": [
{"id":"com.example.timer","name":"Timer","version":"1.0.0","author":"Jane Doe",
"description":"A small timer widget.","icon":"timer","path":"packages/widgets/com.example.timer/timer.bin",
"sha":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"installed_at":1,"source_url":"https://example.org/timer.yaml"}
]
}
```

A package's detail page shows `Author:` and, when the manifest names one, `License:`, with **View
license** to read its text (from `license_url`, or the repository's license file when the manifest
only names the license). A GitHub package also has **View QR code**, which shows its repository
address as a QR code for a phone. When the manifest declares `settings`, the page also has
**Settings...**: one switch per `toggle` and one cycling row per `choice`, saved as they are tapped,
with **Reset all to defaults** at the end. Its values live in
`packages/widgets/<id>/state/settings.json`, as strings keyed by the setting's `key`; a missing or
invalid value reads as its default, and reset removes the file. A license whose files are all
missing does not stop the install when only its name was declared; a `license_url` that does not
answer does.

**Update all** at the top of the package list checks every installed package that has a
`source_url`, one after another, and installs the newer ones; an up-to-date package costs its
manifest's fetch only. The packages were trusted when they were installed, so the batch does not
ask again for each one. An update keeps the old directory as `<id>.previous` until the new one is in
place, so a failed write can be rolled back. Removing a package closes its widget, deletes its files and its
`widgets.ini` line. A package's own state is kept under `packages/widgets/<id>/state/` when the
package is replaced or removed (Remove keeps that folder; nothing else of the package stays). The
host's `settings.json` in that folder is kept too; a package should use another file for its own data.

`spec.runtime` must be `wasm`: a package ships behavior as a WebAssembly module, and Grimoire carries
no widget implementations of its own. A native runtime or entry is refused. The artifact is size-
and SHA-256-checked at install, then instantiated in the frame when it first draws.

A module exports `memory`, `widget_draw(width, height, scale_milli)` and
`widget_tap(hit_id)`, and imports from the `grimoire` module:

```text
rect(x, y, w, h, style)
text(x, y, w, h, ptr, len, px, center)
button(id, x, y, w, h, ptr, len, style)
hit(id, x, y, w, h)
status(ptr, len)
request_redraw(after_ms)
setting(key_ptr, key_len, out_ptr, out_cap) -> i32
state_get(ptr, cap) -> i32
state_set(ptr, len)
now() -> i64
```

Coordinates are screen pixels inside the frame body. `style` is `0` normal, `1` selected or `2`
disabled. Strings are UTF-8 in the module's memory. `request_redraw` names the delay before the
host draws the widget again (16 ms to 24 hours), for a clock or a countdown. `setting` returns the bytes written for one of
the package's saved settings (empty when it is missing); `state_get`/`state_set` read and write the
widget's saved state in `packages/widgets/<id>/state/runtime.bin`, capped at 64 KiB. `status` sets
the text read back by the editor's `editor.widget.N.status` probe. Each call has a fixed instruction
budget and linear memory is capped at 32 MiB, so a looping or greedy widget stops with an error
instead of freezing the device.

[WIDGETS.md](WIDGETS.md#the-wasm-abi) is the guide to writing one.

## `settings.ini`

`key=value` lines; `#` starts a comment line. Readers strip one carriage return at the end of a
Expand Down
Loading
Loading