@pritzlaff/celldeck 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,50 @@
1
- # Temporary Holding Version
1
+ # Cell Deck
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Bubble diagrams you pull apart, connect and present as a sequence of saved views.
4
+
5
+ **[▶ Open Cell Deck](https://aaronp.github.io/celldeck/)** ·
6
+ [Example deck](https://aaronp.github.io/celldeck/?src=examples/acme-architecture/deck.json&view=v-pulled-apart)
7
+
8
+ ## Layout
9
+
10
+ | Path | What |
11
+ |---|---|
12
+ | `index.html` | The page: styles, markup, rendering and input (the "edge"). No build step. |
13
+ | `lib/core.js` | Pure core: data model (TypeBox schemas, incl. the `deck.json` format), scene reducers, physics. |
14
+ | `lib/store.js` | `createDeckStore(storage, key)`: CRUD over a deck (stage + views), validated on every write, backed by `localStorage` (or `memoryStorage()`). |
15
+ | `examples/` | Data-only repos that open in this viewer. Copy one with `make clone` from its folder. |
16
+ | `test/` | `npm test` (Node's built-in runner). |
17
+
18
+ ## Data
19
+
20
+ A deck is one JSON file: `{ version, scene, camera, views: [{ id, name, scene, camera }] }`. See
21
+ `DeckSchema` in `lib/core.js`. `version` is the format version (currently `1`; a file without one is
22
+ read as `1`). A file with a newer version than the page knows is refused rather than misread. Edits are saved in your browser. Use **Download** to save
23
+ `deck.json`, and **Open** to load one from a file (drag-and-drop or pick it) or from a URL.
24
+
25
+ ## Editing a file on disk
26
+
27
+ ```sh
28
+ npx @pritzlaff/celldeck docs/overview/deck.json # creates it if missing
29
+ ```
30
+
31
+ Serves the viewer and that deck on localhost (loopback only) and opens it. The File menu's
32
+ **Save to deck.json** writes the deck back to the file (`PORT=…`, `NO_OPEN=1` as for the other tools).
33
+
34
+ ## Links
35
+
36
+ | Param | Effect |
37
+ |---|---|
38
+ | `?src=<url>` | open that `deck.json` (relative or absolute; another host must allow CORS). It is not saved in your browser, so a shared link never overwrites your work. |
39
+ | `?view=<id or name>` | open that saved view. The address bar follows as you switch views. |
40
+ | `?present` | start in present mode |
41
+
42
+ ## Develop
43
+
44
+ ```sh
45
+ make dev # serves the repo on :8000 (python3); open the printed example URL
46
+ make test
47
+ ```
48
+
49
+ Pushing to `main`/`master` runs the tests, then publishes to GitHub Pages
50
+ (Settings → Pages → Source: **GitHub Actions**).
@@ -0,0 +1,72 @@
1
+ #!/usr/bin/env node
2
+ // celldeck <deck.json>: serves the viewer and that deck on localhost, then opens it in the browser.
3
+ // The deck is re-read on every request, so reloading shows your latest edits; File → Save writes it back (PUT).
4
+ // A missing file is created as an empty deck, so a project can start from `celldeck docs/overview/deck.json`.
5
+ import { createServer } from 'node:http';
6
+ import { readFile, rename, writeFile } from 'node:fs/promises';
7
+ import { spawn } from 'node:child_process';
8
+ import { basename, resolve } from 'node:path';
9
+
10
+ const file = process.argv[2];
11
+ if (!file || file === '-h' || file === '--help') {
12
+ console.error('Usage: celldeck <deck.json> (PORT=8000 to pick the port, NO_OPEN=1 to skip opening a browser)');
13
+ process.exit(file ? 0 : 1);
14
+ }
15
+ const path = resolve(file);
16
+ await readFile(path).catch(async (e) => {
17
+ if (e.code !== 'ENOENT') { console.error(`celldeck: cannot read ${file}: ${e.message}`); process.exit(1); }
18
+ await writeFile(path, JSON.stringify({ version: 1, scene: { bubbles: [], elements: [], links: [] }, camera: { x: 0, y: 0, zoom: 1 }, views: [] }, null, 2) + '\n');
19
+ console.log(`Created ${file}`);
20
+ });
21
+
22
+ const page = (p) => new URL(`..${p}`, import.meta.url);
23
+ const route = '/' + encodeURIComponent(basename(path));
24
+ // Only these routes, so nothing else on disk is reachable.
25
+ const routes = new Map([
26
+ ['/', [page('/index.html'), 'text/html']],
27
+ ['/lib/core.js', [page('/lib/core.js'), 'text/javascript']],
28
+ ['/lib/store.js', [page('/lib/store.js'), 'text/javascript']],
29
+ [route, [path, 'application/json']],
30
+ ]);
31
+ // Loopback names a browser may use for this server. Anything else in Host means DNS rebinding, so it is refused.
32
+ const hosts = (port) => new Set([`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`]);
33
+ const handler = async (req, res) => {
34
+ if (!hosts(server.address().port).has(req.headers.host)) return res.writeHead(403).end('Forbidden host');
35
+ const [target, type] = routes.get(new URL(req.url, 'http://x').pathname) ?? [];
36
+ if (!target) return res.writeHead(404).end('Not found');
37
+ if (req.method === 'PUT' && target === path) {
38
+ // Cross-site pages cannot get here: a JSON PUT needs a CORS preflight, which this server never answers.
39
+ try {
40
+ const chunks = [];
41
+ for await (const c of req) chunks.push(c);
42
+ const body = Buffer.concat(chunks);
43
+ JSON.parse(body); // never replace the deck with something that isn't JSON
44
+ const tmp = `${path}.celldeck-tmp`;
45
+ await writeFile(tmp, body);
46
+ await rename(tmp, path); // whole file or nothing, never half-written
47
+ return res.writeHead(204).end();
48
+ } catch (e) {
49
+ return res.writeHead(e instanceof SyntaxError ? 400 : 500).end(e.message);
50
+ }
51
+ }
52
+ if (req.method !== 'GET' && req.method !== 'HEAD') return res.writeHead(405).end('Method not allowed');
53
+ try {
54
+ const body = await readFile(target);
55
+ // x-celldeck-writable tells the page that Save can PUT the deck back to this URL.
56
+ res.writeHead(200, { 'content-type': `${type}; charset=utf-8`, 'cache-control': 'no-store', ...(target === path ? { 'x-celldeck-writable': '1' } : {}) }).end(body);
57
+ } catch (e) {
58
+ res.writeHead(e.code === 'ENOENT' ? 404 : 500).end(e.message);
59
+ }
60
+ };
61
+ const server = createServer(handler);
62
+
63
+ server.listen(Number(process.env.PORT ?? 0), '127.0.0.1', () => {
64
+ const { port } = server.address();
65
+ // Also answer on ::1 so http://localhost:<port> and http://[::1]:<port> work; skipped if IPv6 loopback is unavailable.
66
+ createServer(handler).on('error', () => {}).listen(port, '::1');
67
+ const url = `http://127.0.0.1:${port}/?src=${route}`;
68
+ console.log(`Serving ${file} at ${url} (Ctrl-C to stop)`);
69
+ if (process.env.NO_OPEN) return;
70
+ const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]];
71
+ spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
72
+ });