webxdc / website Goto Github PK

There are two links in the top-right corner of each page in the documentation (https://webxdc.org/docs/):

1. "Git repository"
2. "Suggest an edit" which directs the reader to the the source file for the page they are currently viewing

These both point to the old docs repo (https://github.com/webxdc/webxdc_docs) which was recently archived.

the following examples are in this repo and somehow ready, but not yet on the website:

• othello
• stackup
• wordle
• draw

seems like https://webxdc.org/apps is not updating properly via xdcget

Especially for sendUpdate and setUpdateListener.

Even "Delta Chat":

Is it intentional?

it leads to old archived repo even though the links in book.toml were already updated:

https://github.com/webxdc/website/blob/main/src-docs/book.toml#L11-L13

Almost everything is written with in lower case on https://webxdc.github.io/website/, even titles or the name Delta Chat. However the "Download" links, "Under construction", "Imprint" and "Privacy Policy" start with an upper case. I'm not a designer, but I would like to suggest to either write everything in lowercase or use the regular capitalization.

Minor suggestion: The first phone screenshot on https://webxdc.github.io/website/ shows the chessboard app in the message view. The subtitle is ellipsized, which looks a little bit odd. It is the very first thing I recognized when I looked at the website. Maybe we can choose an example where the subtitle can be read completely?

For reference, list of common pitfalls in case we implement signatures:
rust-lang/cargo#7212 (comment)

In particular, hashing .zip contents instead of the file itself is tricky if you use different zip implementation on different platforms. In case of deltachat core it may be fine as the same core is used by all apps, but Cheogram may decompress zip files differently using a different .zip implementation.

Bots using WebXDC as a frontend web interface, such as https://codeberg.org/webxdc/store and https://github.com/deltachat-bot/public-bots need a way to upgrade the frontend while keeping already sent WebXDC updates.

Current plan is to add API that will allow the WebXDC to upgrade itself by calling a JavaScript API with a blob containing new .xdc file. WebXDC app will retrieve an update from the bot as an update, e.g. as a base64-string.

Core PR adding dc_replace_webxdc(context, msg_id, blob, n) API: deltachat/deltachat-core-rust#4740
Android issue about adding a JavaScript API for dc_replace_webxdc: deltachat/deltachat-android#2656

Previous idea was to allow the bot to send an upgrade directly: deltachat/deltachat-core-rust#4532
However, it was abandoned due to backwards compatibility problems. If the client does not support upgrading, this would result in the bot thinking that there is a single upgraded WebXDC instance, while the client will have two WebXDC instances, old one and upgraded one, and WebXDC updates from the bot will only be assigned to one of them.

New dc_replace_webxdc API would also allow the app to modify itself, this should be kept in mind wrt. security of WebXDC. Upgrading the app can modify the manifest of the app, so if the manifest is going to contain permissions or capabilities of the app (e.g. network access), the app modifying the manifest will be able to add new permissions to itself. Another problem is that by embedding updates into the .xdc, the app may be able to exfiltrate updates normally contained within the chat when it is saved to the disk or forwarded.

qr code data is DCACCOUNT:https://mailadm.try.webxdc.org/?t=90d_f7v5c5xrtntpkqe&n=try90d

we should try to make the screenshots and borders a bit smaller, so that 2 examples fit in a row also on common mobiles.

But the website doesn't link to it. We have "Search for more apps on GitHub", we could also add something like "or send 'hi' to ... from Delta Chat", or maybe dedicate a section to it. Besides the blog and the store repo do we have other resources talking about it?
I think it still makes sense to keep the direct download links to not overly complicate things for developers, so that it's immediately clear that apps are basically just files, and the app store is an auxiliary thing.

i manually used "cargo install mdbook-linkchecker" and added "[output.linkcheck]" and found various link issues.
Should be part of CI.

I think that https://webxdc.org/apps/ might be a very important page and a big source of user traction, especially of potential new users of Delta Chat. Why? Because this is an app store, and collectively the apps cover a large amount of search queries. For example, a search for "collaborative text editor" should show this page.
Being a super-app is a big selling point of Delta Chat, and other webxdc-runtime messengers.

So, to be more specific:

• Each app must have a separate page. I know the list is generated client-site, but IIRC at least Google is capable of crawling PWA pages. Maybe we could also consider server-side rendering (SSR). At the very least we need to add a router, like in React and Vue.
• The page should be self-contained, without assuming that users know what Delta Chat or webxdc is.

• website/apps/index.html

  Line 7 in d8ee4e4

  <!-- TODO meta tags to be found by search engines -->

maybe add video from https://github.com/deltachat/webxdc_website

Basically revert a3abc62.

I think it adds confusion, e.g. some may assume that this technology works in all the messengers, they'll be puzzled by how it works. I know that they can figure it out after a bit of digging, but sooner is better, I think.

I think to better understand how to write things we need to answer here for whom the website is made primarily. Is it regular users, messenger developers, or app developers? I think it's the latter. So I'm for making it clear that only Delta Chat supports webxdc for now.

tictactoe.xdc comes as a tournament, therefore another class of game examples.

It seems like the mdbook-linkcheck crate is missing from the installation instructions. mdbook build throws an error if it is not present. I thought I had copied the error, but now I can't find it, but it should be easy to reproduce for anyone that doesn't have the dependency already.

I was able to get things working with cargo install mdbook-linkcheck, but I'm not a rust expert and so I'm not sure if this should just be added to src-docs/readme.md or if there should be a cargo.lock file added.

Looking at the specification https://webxdc.org/docs/spec/format.html I find some potential issues / questions regarding the format:

XDC Format

• ZIP settings such as compression, etc, are not defined explicitly

• Make the zipping process reproducible: Last-modified timestamps & File-system permissions (mode) for the archive files.

• Specify a max file size. (I belive this is already the case as see here https://github.com/webxdc/hello/blob/d648febd18ec809ecbd5681f1fc6d4b5273b3e52/create-xdc.sh#L23 )

• manifest toml file does not define if additional properties are allowed

• clarify where it says that manifest toml says if manifest.toml exists it MUST read source_code_url however this is stated as an optional field.

Suggestions

• define a 'scope' for which html pages can be loaded besides index.html for the user. E.g. a 'debug' page may be scoped for development purposes but disabled for normal installs
• an "integrity hash" or SRI hash, which is basically a checksum over the source file inputs. it is intended to let consumers easily validate

we can use delta.chat and its blog as a template, there it works :)

there was also a testing site somewhere ...

We do lower-casing for style (see #32, #7). It can take time to change it if we decide to. So I think writing things in normal case, and simply transforming it with CSS is simpler.
Also not sure, but it may affect screen-readers.