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 .github/workflows/deploy-pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ jobs:
working-directory: client

# Project Pages live at jonocodes.github.io/deckd/: the homepage
# (site/) at the root, the client at /deckd/app/, Ladle at
# (site/) at the root, the client at /deckd/demo/client/, Ladle at
# /deckd/ladle/. The same script backs `just pages`, so a local
# preview is exactly what deploys; it type-checks the client first,
# so a type error fails the deploy before a broken bundle ships.
Expand Down
13 changes: 8 additions & 5 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -205,7 +205,7 @@ build-client:
cd client && npm run build

# Assemble the GitHub Pages site exactly as the deploy workflow does: the
# homepage at the root, the client under app/, Ladle under ladle/.
# homepage at the root, the client under demo/client/, Ladle under ladle/.
# Output: _site/deckd/. `just pages` builds and serves it.
build-pages:
scripts/build_pages.sh _site/deckd
Expand All @@ -221,14 +221,17 @@ screenshots:
cd client && node screenshots.mjs

# Build the GitHub Pages site exactly as CI deploys it (homepage at /deckd/,
# client at /deckd/app/, Ladle at /deckd/ladle/) and serve it on :5290.
# SKIP_LADLE=1 just pages skips the slow Ladle build.
# client at /deckd/demo/client/, Ladle at /deckd/ladle/) and serve it on :5290.
# SKIP_LADLE=1 just pages skips the slow Ladle build; PAGES_HOST=0.0.0.0
# serves it to other devices too (e.g. over Tailscale).
pages:
#!/usr/bin/env bash
set -euo pipefail
scripts/build_pages.sh _site/deckd
echo "Pages preview: http://127.0.0.1:5290/deckd/"
node scripts/serve_pages.mjs _site 5290
host="${PAGES_HOST:-127.0.0.1}"
[ "$host" = 0.0.0.0 ] && shown="$(hostname)" || shown="$host"
echo "Pages preview: http://$shown:5290/deckd/ (demo: /deckd/demo/)"
node scripts/serve_pages.mjs _site 5290 "$host"

# Preview the homepage mockups (docs/mockups/homepage) over http. The client's
# Vite dev server on :5288 serves the demo decks the pages embed; a static
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# deckd

**[jonocodes.github.io/deckd](https://jonocodes.github.io/deckd/)** — homepage, with the client running live in demo mode.
**[jonocodes.github.io/deckd](https://jonocodes.github.io/deckd/)** — homepage · **[live demo](https://jonocodes.github.io/deckd/demo/)**: pick an app, see its deck.

App-aware touch control surface for your desktop. A Stream Deck-like deck of buttons, sliders, scroll strips, and a manual control mode (a single combined trackpad + keyboard passthrough), rendered in any browser on any touchscreen device, driven by a local daemon that watches the focused application and swaps decks automatically.

Expand Down
5 changes: 2 additions & 3 deletions client/src/Gallery.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,7 @@ type Device = { label: string; w: number; h: number };

// Portrait base dimensions (CSS px); landscape swaps w/h.
const DEVICES: Device[] = [
{ label: "Phone", w: 390, h: 844 },
{ label: "Large phone", w: 430, h: 932 },
{ label: '7" tablet', w: 600, h: 1024 },
{ label: '10" tablet', w: 834, h: 1194 },
];

Expand All @@ -29,7 +27,8 @@ const MAX_H = 360;

type Orientation = "landscape" | "portrait";

const DEMO_LABELS: Record<string, string> = { mpris: "Media" };
// ``media`` is the showcase now-playing deck; ``mpris`` is the test fixture.
const DEMO_LABELS: Record<string, string> = { mpris: "MPRIS" };

function Frame({
device,
Expand Down
21 changes: 21 additions & 0 deletions client/src/demo-landing.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
import { describe, expect, it } from "vitest";
import { demoLanding } from "./demo-landing";

describe("demo landing (GitHub Pages build)", () => {
const target = "/deckd/demo/";

it("forwards a visit with nothing to show to the demo page", () => {
expect(demoLanding("", target)).toBe(target);
});

it("leaves demo, playground and pinned-deck links alone", () => {
expect(demoLanding("?demo=firefox", target)).toBeNull();
expect(demoLanding("?playground", target)).toBeNull();
expect(demoLanding("?deck=youtube", target)).toBeNull();
});

it("does nothing outside the Pages build (no target configured)", () => {
expect(demoLanding("", undefined)).toBeNull();
expect(demoLanding("", "")).toBeNull();
});
});
11 changes: 11 additions & 0 deletions client/src/demo-landing.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
/** On GitHub Pages there's no daemon, so the client with nothing to show
* (no ``?demo=`` / ``?playground`` / ``?deck=``) just says "Reconnecting…".
* The Pages build sets ``VITE_DEMO_PAGE`` (scripts/build_pages.sh) and such a
* visit forwards there instead. The client is also the site's 404.html, so a
* mistyped site link lands on the demo too. Unset everywhere else, so a
* daemon-served client never redirects. */
export function demoLanding(search: string, target: string | undefined): string | null {
if (!target) return null;
const params = new URLSearchParams(search);
return params.has("demo") || params.has("playground") || params.has("deck") ? null : target;
}
16 changes: 11 additions & 5 deletions client/src/main.tsx
Original file line number Diff line number Diff line change
@@ -1,12 +1,18 @@
import React from "react";
import ReactDOM from "react-dom/client";
import { App } from "./App";
import { demoLanding } from "./demo-landing";
import "./fonts";
import "./style.css";
import "./help.css";

ReactDOM.createRoot(document.getElementById("root")!).render(
<React.StrictMode>
<App />
</React.StrictMode>,
);
const landing = demoLanding(window.location.search, import.meta.env.VITE_DEMO_PAGE);
if (landing) {
window.location.replace(landing);
} else {
ReactDOM.createRoot(document.getElementById("root")!).render(
<React.StrictMode>
<App />
</React.StrictMode>,
);
}
14 changes: 7 additions & 7 deletions client/src/view-routing.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,23 +19,23 @@ describe("view routing", () => {
expect(viewFromPath("/not-a-page")).toBe("deck");
});

// Served under a sub-path (GitHub Pages: /deckd/app/), every view lives
// Served under a sub-path (GitHub Pages: /deckd/demo/client/), every view lives
// beneath the base, and paths outside it aren't views.
describe("under a base path", () => {
const base = "/deckd/app/";
const base = "/deckd/demo/client/";

it.each([
["/deckd/app/", "deck"],
["/deckd/app/trackpad", "trackpad"],
["/deckd/app/now-playing", "nowplaying"],
["/deckd/app/help", "help"],
["/deckd/demo/client/", "deck"],
["/deckd/demo/client/trackpad", "trackpad"],
["/deckd/demo/client/now-playing", "nowplaying"],
["/deckd/demo/client/help", "help"],
] as const)("maps %s to %s", (path, view) => {
expect(viewFromPath(path, base)).toBe(view);
expect(pathForView(view, base)).toBe(path);
});

it("treats the base without its trailing slash as the deck", () => {
expect(viewFromPath("/deckd/app", base)).toBe("deck");
expect(viewFromPath("/deckd/demo/client", base)).toBe("deck");
});

it("doesn't read a root-level path as a view", () => {
Expand Down
2 changes: 1 addition & 1 deletion client/src/view-routing.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ const VIEW_BY_PATH: Record<string, View> = Object.fromEntries(
) as Record<string, View>;

// Views live under the app's base path: "/" when the daemon serves the
// client, "/deckd/app/" on GitHub Pages (Vite's ``base``, from
// client, "/deckd/demo/client/" on GitHub Pages (Vite's ``base``, from
// VITE_BASE_PATH). The trailing slash is dropped so "/" joins as "".
const prefix = (base: string) => base.replace(/\/+$/, "");

Expand Down
5 changes: 5 additions & 0 deletions client/src/vite-env.d.ts
Original file line number Diff line number Diff line change
@@ -1 +1,6 @@
/// <reference types="vite/client" />

interface ImportMetaEnv {
/** Pages build only: where a visit with no demo to show is sent. */
readonly VITE_DEMO_PAGE?: string;
}
4 changes: 2 additions & 2 deletions client/vite.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,9 @@ const daemonUpstream = process.env.DECKD_UPSTREAM ?? "http://127.0.0.1:8865";
const https = readTlsConfig();

export default defineConfig({
// On Pages the client lives at jonocodes.github.io/deckd/app/ (the
// On Pages the client lives at jonocodes.github.io/deckd/demo/client/ (the
// homepage has /deckd/): scripts/build_pages.sh sets
// ``VITE_BASE_PATH=/deckd/app/``. Local dev and the daemon-served build
// ``VITE_BASE_PATH=/deckd/demo/client/``. Local dev and the daemon-served build
// leave ``base`` at the default ``/``.
base: process.env.VITE_BASE_PATH ?? "/",
plugins: [react()],
Expand Down
15 changes: 8 additions & 7 deletions docs/GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -220,13 +220,14 @@ The client can be viewed and design-iterated without a running daemon:

Every push to `main` builds the homepage, the client and Ladle and publishes them to GitHub Pages, so the previews above can be browsed with no daemon and no local checkout. `scripts/build_pages.sh` assembles the site, and `just pages` builds and serves the same thing locally on :5290.

- **Homepage** — `https://jonocodes.github.io/deckd/`. Source in `site/`; its phones embed the client's showcase demo decks (`?demo=home`, `gmail`, `meet`, `media`, …).
- **Live client (demo mode)** — `https://jonocodes.github.io/deckd/app/?demo=showcase` (also `?demo=firefox`, `?demo=home`). Without `?demo=` the client loads and shows "disconnected" since there's no daemon behind the Pages site; the param lets the fixture deck run. Deep links to a view (`app/trackpad`) work too: the site's `404.html` is the client.
- **Responsive gallery** — `https://jonocodes.github.io/deckd/app/gallery.html`.
- **Layout help** — `https://jonocodes.github.io/deckd/app/help.html`. The standalone build of the in-app explainer (below); no daemon, no icons.
- **Ladle stories** — `https://jonocodes.github.io/deckd/ladle/`.

Source: `.github/workflows/deploy-pages.yml`. The client builds with `VITE_BASE_PATH=/deckd/app/` and Ladle with `--base /deckd/ladle/` so the Project-Pages sub-paths resolve; local dev keeps base `/`. `just build-pages` assembles the same tree into `_site/deckd/`; `just pages` builds and serves it.
- **Homepage** — [jonocodes.github.io/deckd/](https://jonocodes.github.io/deckd/). Source in `site/`; its phones embed the client's showcase demo decks (`?demo=home`, `gmail`, `meet`, `media`, …).
- **Live demo** — [jonocodes.github.io/deckd/demo/](https://jonocodes.github.io/deckd/demo/). Pick an app on a pretend desktop and the client (below) switches to its deck. Source in `site/demo/`.
- **Demo client** — `demo/client/` is the real client running on pretend data. It's there only for the homepage and the demo page to embed (`demo/client/?demo=gmail`, …), so nothing links to it; a visit without `?demo=` (or `?playground`) forwards to the demo page (`VITE_DEMO_PAGE`, set by `scripts/build_pages.sh`). A daemon-served client never redirects. Deep links to a view (`demo/client/trackpad?demo=firefox`) work because the site's `404.html` is the client.
- **Responsive gallery** — [jonocodes.github.io/deckd/demo/client/gallery.html](https://jonocodes.github.io/deckd/demo/client/gallery.html).
- **Layout help** — [jonocodes.github.io/deckd/demo/client/help.html](https://jonocodes.github.io/deckd/demo/client/help.html). The standalone build of the in-app explainer (below); no daemon, no icons.
- **Ladle stories** — [jonocodes.github.io/deckd/ladle/](https://jonocodes.github.io/deckd/ladle/).

Source: `.github/workflows/deploy-pages.yml`. The client builds with `VITE_BASE_PATH=/deckd/demo/client/` and Ladle with `--base /deckd/ladle/` so the Project-Pages sub-paths resolve; local dev keeps base `/`. `just build-pages` assembles the same tree into `_site/deckd/`; `just pages` builds and serves it (`PAGES_HOST=0.0.0.0 just pages` to reach it from another device, e.g. over Tailscale).

### PWA install over HTTPS (Tailscale)

Expand Down
2 changes: 1 addition & 1 deletion docs/ONBOARDING.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ This document is the primary navigation map for AI agents (and human developers)
│ ├── kwin-script/ # KWin focus script (KDE Plasma Wayland)
│ └── gnome-shell/ # GNOME Shell focus extension
├── scripts/ # Diagnostic and testing utilities; build_pages.sh assembles the Pages site
├── site/ # GitHub Pages homepage (jonocodes.github.io/deckd/); the client deploys under app/
├── site/ # GitHub Pages homepage (jonocodes.github.io/deckd/); the client deploys under demo/client/ (embedded by the homepage and demo page)
├── tests/ # Python test suite (pytest + pytest-asyncio)
└── docs/ # Documentation (see below)
├── GUIDE.md # User & setup guide: install, per-platform setup, config walkthrough, client features, dev loop
Expand Down
6 changes: 3 additions & 3 deletions docs/mockups/homepage/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ just mockups
# → http://127.0.0.1:5289/docs/mockups/homepage/a-notebook.html (and c-press.html)
# → http://127.0.0.1:5289/site/index.html?app=http://127.0.0.1:5288/ (B, live dev client)
just pages
# → http://127.0.0.1:5290/deckd/ (B exactly as deployed: built site, client at app/)
# → http://127.0.0.1:5290/deckd/ (B exactly as deployed: built site, client at demo/client/)
```

The phones show the showcase demo decks (`?demo=home`, `gmail`, `meet`,
Expand All @@ -38,6 +38,6 @@ directly: a `file://` page can't frame localhost in current browsers, so the
phones stay blank.

`?app=<url>` points the phones at another client. The homepage defaults to the
client beside it (`app/`); A and C fall back to the public build at
`https://jonocodes.github.io/deckd/app/`. Add `?eager` to load every phone
client beside it (`demo/client/`); A and C fall back to the public build at
`https://jonocodes.github.io/deckd/demo/client/`. Add `?eager` to load every phone
up front (for full-page screenshots).
11 changes: 7 additions & 4 deletions scripts/build_pages.sh
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
#!/usr/bin/env bash
# Assemble the GitHub Pages site: the homepage (site/) at the root, the client
# under app/, Ladle under ladle/. CI (.github/workflows/deploy-pages.yml) and
# under demo/client/ (it only exists to be embedded by the homepage and the
# demo page), Ladle under ladle/. CI (.github/workflows/deploy-pages.yml) and
# `just pages` both run this, so a local preview is exactly what deploys.
#
# Usage: scripts/build_pages.sh [OUT_DIR] (default: _site)
Expand All @@ -20,12 +21,14 @@ cp -rL "$root/site/." "$out/"

cd "$root/client"
# `npm run build` type-checks first, so a type error fails the deploy.
VITE_BASE_PATH="${base}app/" npm run build -- --outDir "$out/app" --emptyOutDir
# VITE_DEMO_PAGE: with no daemon here, a visit with no demo to show forwards to
# the demo page (client/src/demo-landing.ts) instead of "Reconnecting…".
VITE_BASE_PATH="${base}demo/client/" VITE_DEMO_PAGE="${base}demo/" npm run build -- --outDir "$out/demo/client" --emptyOutDir

# Pages serves the site's 404.html for any unknown path. Make it the client,
# so a deep link like app/trackpad boots the app (its asset URLs are
# so a deep link like demo/client/trackpad boots the app (its asset URLs are
# absolute, so they resolve from any path) instead of a bare 404.
cp "$out/app/index.html" "$out/404.html"
cp "$out/demo/client/index.html" "$out/404.html"

if [ -z "${SKIP_LADLE:-}" ]; then
# Ladle won't create its outDir, and joins even an absolute --outDir onto
Expand Down
6 changes: 4 additions & 2 deletions scripts/serve_pages.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@
// static files, `dir/` → `dir/index.html`, and the site's 404.html (with a
// 404 status) for anything else — which is what makes app deep links work.
//
// Usage: node scripts/serve_pages.mjs <root> [port] (default port 5290)
// Usage: node scripts/serve_pages.mjs <root> [port] [host]
// (default port 5290, host 127.0.0.1; 0.0.0.0 to reach it from another device)
// <root> is the directory holding the site under its base, e.g. _site for
// _site/deckd/.
import { createServer } from "node:http";
Expand All @@ -11,6 +12,7 @@ import { extname, join, normalize, resolve } from "node:path";

const root = resolve(process.argv[2] ?? "_site");
const port = Number(process.argv[3] ?? 5290);
const host = process.argv[4] ?? "127.0.0.1";
const TYPES = {
".html": "text/html; charset=utf-8", ".js": "text/javascript", ".mjs": "text/javascript",
".css": "text/css", ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png",
Expand Down Expand Up @@ -40,4 +42,4 @@ createServer(async (req, res) => {
if (!path) return res.writeHead(404).end("not found");
res.writeHead(status, { "content-type": TYPES[extname(path)] ?? "application/octet-stream" });
res.end(await readFile(path));
}).listen(port, "127.0.0.1", () => console.log(`serving ${root} on http://127.0.0.1:${port}/`));
}).listen(port, host, () => console.log(`serving ${root} on http://${host}:${port}/`));
Loading
Loading