Basic stuff

= Events =

We need events. Many of them.

HTML to Harness - events fired by the HTML page which are picked up by the wrapper

- item-dropped - a dragged-in thing has been dropped on a bucket
  Parameters: bucket_name (string), item (dict: { mimetype: string, uri: string } )

- item-deleted - an item already in a bucket has been deleted
  Parameters: item_id - string

- item-edited - an item already in a bucket has been edited
  Parameters: item_id (string), item (dict: all the metadata )

- bucket-created - a new bucket is created
  Parameters: bucket_name (string)

- bucket-deleted - a bucket is deleted
  Parameters: bucket_name (string)

- item_open_native - the user wants to open this item. The harness is expected to open it in the OS, whatever that means
  Parameters: id (string)

Harness to HTML - events fired by the wrapper which are picked up by the HTML page

- item-created - a dragged-in thing has been dropped. Contains a bucket name. Create new items in response to this event, *not* before firing your own item-dropped event (because this one contains the ID). This event is also fired for each already-existing item on startup
  Parameters: bucket_name (string), item (dict: { item_id: string, mimetype: string, uri: string, some other metadata depending on item type } )

- item-deleted - an item already in a bucket has been deleted. (NB: the harness will only fire this if a deletion is synced from another machine; on this machine, deletions are done by the HTML)
  Parameters: item_id - string

- item-edited - an item already in a bucket has been edited. (NB: the harness will only fire this if an edit is synced from another machine; on this machine, edits are done by the HTML)
  Parameters: item_id (string), item (dict: all the metadata )

- bucket-created - a new bucket is created. (NB: the harness will only fire this if a creation is synced from another machine; on this machine, creations are done by the HTML). This event is also fired for each already-existing bucket on startup
  Parameters: bucket_name (string)

- bucket-deleted - a bucket is deleted. (NB: the harness will only fire this if a deletion is synced from another machine; on this machine, deletions are done by the HTML)
  Parameters: bucket_name (string)

= On-disk layout =

Top-level folder: ~/.buckets
(I wish this could be .local/share/buckets, but some machine have .local/share being a different folder, and U1 can't do that. :( )

Under that:

~/.buckets/buckets - container for all buckets; this means that we can put other stuff in ~/.buckets and it'll be synced (yay) but isn't user data
~/.buckets/buckets/bucket_name - one folder per bucket - bucket_name is a urlencoded version of the actual bucket name
~/.buckets/buckets/metadata.json - metadata file about the bucket itself (contains bucket_name key, so that bucket names don't need to be a valid filename and you can have a bucket called AC/DC if you want)
~/.buckets/buckets/bucket_name/item_id - one folder per item - id is chosen by the harness, and is not user-visible
~/.buckets/buckets/bucket_name/item_id/metadata.json - metadata about the item
~/.buckets/buckets/bucket_name/item_id/filename.ext - the actual item itself
~/.buckets/buckets/bucket_name/item_id/thumbnails/100x100.jpg - a thumbnail. There will be many thumbnails in different sizes

= Item types =

Item types we understand, and the metadata we hold about them. (This is the metadata in "some metadata" above.)

All items have the following metadata:
  id: string
  thumbnails: [ WxH: uri, WxH: uri, ... ]
  annotations: [ { id: string, text: string, date_created: ctime }, ... ]
  date_created: ctime

Text notes: { text: text of note }
HTML notes: { html: html of note }
Images: { uri: a uri to display that image in full, width: int, height: int }
Files: { name: string } (the HTML should use the item_open_native event to perform actions on this file)