+ goTo(tabOfExample(slug, tabs))}
+ />
+
+ )}
+ {page === "home" && (
- - Install the browser extension. The extension rather than the Figma plugin - alone, because the plugin fetches a public address from Figma's servers and a - canvas on localhost is not one — the extension reads the page from inside the - browser that already has it open. + Install the browser extension. The extension rather than + the Figma plugin alone, because the plugin fetches a public + address from Figma's servers and a canvas on localhost is not one + — the extension reads the page from inside the browser that + already has it open. {/* The one thing on this page that has to be done before anything else works, so it is a button and not the third link in a paragraph. */} Add html.to.design to your browser - Free · Chrome, Edge, Brave, Arc and other Chromium browsers + + Free · Chrome, Edge, Brave, Arc and other Chromium browsers + ↗ @@ -83,16 +87,18 @@ export function BoardsSheet({ slug }: { slug: string }) {
- - Capture this page. Click the extension's icon while this tab is in front, - leave the viewport on Browser, and press Capture Current Page. It - reads every board below at the size it ships at, rather than the zoomed-out - thumbnail the canvas shows. + Capture this page. Click the extension's icon while this + tab is in front, leave the viewport on Browser, and press{" "} + Capture Current Page. It reads every board below at the + size it ships at, rather than the zoomed-out thumbnail the canvas + shows.
-
- Paste it into Figma. Pick Copy to clipboard and press ⌘V in a Figma
- file; that route needs no plugin at all. The plugin is for the other two routes —
- sending the capture straight over, or opening a saved
.h2dfile. - Either way the boards arrive as editable layers, not as images. + Paste it into Figma. Pick Copy to clipboard and + press ⌘V in a Figma file; that route needs no plugin at all. The + plugin is for the other two routes — sending the capture straight + over, or opening a saved.h2dfile. Either way the + boards arrive as editable layers, not as images. shape.type === CANVAS_LINK_SHAPE_TYPE && shape.isLocked, + filter: (shape) => + shape.type === CANVAS_LINK_SHAPE_TYPE && shape.isLocked, }) as CanvasLinkShape | undefined; let pressed: CanvasLinkShape | undefined; @@ -270,7 +271,10 @@ export class CanvasLinkShapeUtil extends BaseBoxShapeUtil{ override onClick(shape: CanvasLinkShape) { if (shape.props.url) { - window.open(shape.props.url, "_blank", "noopener,noreferrer"); + // A web address only: a layout.json can come from someone else's project, and a + // `javascript:` one would run in the canvas. + if (/^https?:/i.test(shape.props.url)) + window.open(shape.props.url, "_blank", "noopener,noreferrer"); return; } const page = this.editor diff --git a/canvas/src/CanvasTabBar.tsx b/canvas/src/CanvasTabBar.tsx index 8a53abfa..64846628 100644 --- a/canvas/src/CanvasTabBar.tsx +++ b/canvas/src/CanvasTabBar.tsx @@ -17,7 +17,7 @@ import { import type { CanvasTab } from "./canvasUrl"; import type { Working } from "./ChatPanel"; import { askServer, openMenu, REVEAL } from "./contextMenu"; -import { Cross, Home, Plus } from "./geistIcons"; +import { Cross, Home, Plus, Users } from "./geistIcons"; /** * The bar across the top of the window: the agent's button, which AppShell.tsx hands in as @@ -103,6 +103,8 @@ export function CanvasTabBar(props: { /** What the agent is writing to: a project behind the one in front has a sheen cross its name while it is. */ working: Working; onHome: () => void; + /** The community's chip, while it is open: opened from the home page, and never a project's. */ + community?: { active: boolean; open: () => void; close: () => void }; goTo: (tab: ProjectTab) => void; /** Takes these off the bar, landing on a neighbour when the one in front goes. */ closeTabs: (tabs: ProjectTab[]) => void; @@ -127,13 +129,37 @@ export function CanvasTabBar(props: { onContextMenu={(event) => openMenu(event, menu, () => setTarget("home")) } - aria-current={active ? undefined : "page"} + aria-current={active || props.community?.active ? undefined : "page"} title="Home" onClick={props.onHome} > + {props.community && ( + + + + + )} {tabs.map((tab) => (FAMILIES.find(([k]) => k === f)![1]; + +/** Picked by hand. A slug this build does not have is left out. */ +const COLLECTIONS = [ + { + id: "ai", + title: "AI assistants", + desc: "Chat, ask, get things done.", + slugs: ["claude-ios", "chatgpt-ios", "perplexity-ios", "grok-ios"], + }, + { + id: "social", + title: "Social feeds", + desc: "Scroll, post, connect.", + slugs: ["instagram-ios", "x-ios", "tiktok-ios", "substack-ios"], + }, + { + id: "apple", + title: "Apple's own", + desc: "The apps the phone comes with.", + slugs: [ + "apple-wallet", + "apple-photos", + "apple-calendar", + "apple-settings", + "apple-app-store", + "apple-home-lock", + ], + }, + { + id: "work", + title: "Tools", + desc: "Notes, launchers, events.", + slugs: ["notion-ios", "raycast-ios", "snapaction-ios", "luma-ios"], + }, +]; + +interface Entry { + /** An example's slug, or a shared project's id. */ + slug: string; + name: string; + boards: number; + family: Family; + updated: number; + author: string; + contributors: string[]; + icon?: string; + /** Its thumbnail.png, as `sp pack -o` or `sp thumbnail` drew it. */ + thumbnail: string; + /** A shared project's folder on GitHub. */ + source?: string; +} + +/** index.json, as the community repo's CI writes it (.github/community.py there). */ +interface Index { + projects: { + id: string; + name: string; + author: { login: string }; + contributors: { login: string }[]; + boards: number; + device: string; + thumbnail: string; + icon: string | null; + updated: string; + }[]; +} + +const shared = (index: Index): Entry[] => + index.projects.map((p) => ({ + slug: p.id, + name: p.name, + boards: p.boards, + family: FAMILIES.some(([k]) => k === p.device) + ? (p.device as Family) + : "web", + updated: Date.parse(p.updated), + author: p.author.login, + contributors: p.contributors.map((c) => c.login), + icon: p.icon ? RAW + p.icon : undefined, + thumbnail: RAW + p.thumbnail, + source: `${COMMUNITY}/tree/main/projects/${p.id}`, + })); + +function examples(): Entry[] { + return canvasIndex() + .boards.filter((b) => b.example && b.icon && b.thumbnail) + .map((b) => { + const cover = projectCover([b])!; + return { + slug: b.slug, + name: shortName(b.slug), + boards: b.html.length, + // The phone artboard every clone draws on; anything wider is a page. + family: + cover.w === CANVAS_FILE_DEFAULT_SIZE.w && + cover.h === CANVAS_FILE_DEFAULT_SIZE.h + ? "iphone" + : "web", + thumbnail: canvasThumbnailUrl(b.slug)!, + updated: b.updated, + author: EXAMPLES_BY, + contributors: [], + icon: canvasIconUrl(b.slug), + }; + }); +} + +const plural = (n: number) => `${n} board${n === 1 ? "" : "s"}`; +const avatar = (login: string) => `https://github.com/${login}.png?size=64`; + +/** A project's thumbnail.png, at the Open Graph image's 1200:630 it is drawn at. */ +function Thumb({ entry }: { entry: Entry }) { + return ( + ++ ); +} + +function Card({ entry, onOpen }: { entry: Entry; onOpen: () => void }) { + return ( ++
- + +
+ ); +} + +/** + * @param openExample The app's: opens a project as its tab. Without it, as on the site, Open is + * a link to the demo canvas. + */ +export function CommunityPage({ + openExample, +}: { + openExample?: (slug: string) => void; +}) { + const [all, setAll] = useState(examples); + const [family, setFamily] = useState("all"); + const [collection, setCollection] = useState (null); + const [q, setQ] = useState(""); + const [open, setOpen] = useState (null); + /** Which project's link was copied, so another one opened says Copy again. */ + const [copied, setCopied] = useState (null); + const search = useRef (null); + const tabs = useRef (null); + const dialog = useRef (null); + + const collections = COLLECTIONS.map((c) => ({ + ...c, + entries: c.slugs + .map((s) => all.find((e) => e.slug === s)) + .filter((e) => e !== undefined), + })).filter((c) => c.entries.length > 0); + const col = collections.find((c) => c.id === collection); + const needle = q.trim().toLowerCase(); + const shown = all.filter( + (e) => + (family === "all" || e.family === family) && + (!col || col.slugs.includes(e.slug)) && + (!needle || + [ + e.name, + e.author, + familyName(e.family), + ...collections + .filter((c) => c.slugs.includes(e.slug)) + .map((c) => c.title), + ].some((t) => t.toLowerCase().includes(needle))), + ); + + // "/" is search, as on the site this was drawn after, unless something is being typed into. + useEffect(() => { + const onKey = (event: KeyboardEvent) => { + const typing = (event.target as Element).closest?.( + "input, textarea, [contenteditable], dialog", + ); + if (event.key === "/" && !typing) { + event.preventDefault(); + search.current?.focus(); + } + }; + addEventListener("keydown", onKey); + return () => removeEventListener("keydown", onKey); + }, []); + + // Offline, or with GitHub down, the page lists the examples alone. + useEffect(() => { + fetch(`${RAW}index.json`) + .then((r) => (r.ok ? r.json() : Promise.reject(r.status))) + .then((index: Index) => setAll([...shared(index), ...examples()])) + .catch(() => {}); + }, []); + + useEffect(() => { + if (open && !dialog.current!.open) dialog.current!.showModal(); + if (!open && dialog.current!.open) dialog.current!.close(); + }, [open]); + + const pickCollection = (id: string) => { + const same = collection === id; + setCollection(same ? null : id); + setFamily("all"); + setOpen(null); + if (!same) + tabs.current!.scrollIntoView({ block: "start", behavior: "smooth" }); + }; + + return ( + ++ ); +} diff --git a/canvas/src/HomePage.tsx b/canvas/src/HomePage.tsx index dffe96f1..81dcabdf 100644 --- a/canvas/src/HomePage.tsx +++ b/canvas/src/HomePage.tsx @@ -26,7 +26,7 @@ import { setProjectCover, TRASH, } from "./contextMenu"; -import { FolderPlus, LogoDiscord, LogoGithub, Plus } from "./geistIcons"; +import { FolderPlus, LogoDiscord, LogoGithub, Plus, Users } from "./geistIcons"; type Sort = "edited" | "name" | "boards"; /** A card's right-click: the address it links to, the tab it opens, and its project if it is one. */ @@ -62,14 +62,76 @@ function ago(ms: number) { return "just now"; } +/** + * A cover at `scale`, placed at `place` in its stage. A board is a picture of it, `/__sp/shoot`'s, + * which the server draws once per edit, so a page of forty cards is forty images rather than forty + * documents. Where there is nothing to draw it, a build with no server or a machine without refkit, + * it is the board itself in a frame, sandboxed because a thumbnail has nothing to run. An image is + * the file itself. + */ +function CoverPicture(props: { + cover: Cover; + /** The address its files are under: the project's, or this page's for an example. */ + base: string; + /** When it was last edited, so a board written since is shot again. */ + updated: number; + title: string; + scale: number; + place: { left: number; top: number }; +}) { + const { cover, base, scale, place } = props; + const [live, setLive] = useState(!canvasIndex().served); + const file = `${base}board/${encodeURI(cover.path)}`; + const board = cover.path.endsWith(".html"); + return board && live ? ( + + ) : ( ++ + ++ Discover community-made real app clones, +
+ +
+ device mockups and{" "} + editable boards ++ {FAMILIES.map(([key, label, Icon]) => { + const n = + key === "all" + ? all.length + : all.filter((e) => e.family === key).length; + return ( + + ); + })} ++ {col && ( ++ Collection + + {col.title} + + ++ )} +-
+ {shown.map((e) => (
+
-
+ {needle ? (
+ <>
+
+ Nothing matches “{q.trim()}”
+Try another name, or clone it yourself and share it.
+ + + ) : ( + <> +No {familyName(family)} projects yet
++ {col + ? `Nothing in “${col.title}” for ${familyName(family)}.` + : "Be the first to clone one and share it."} +
+ + Share the first one+ + + )} +
+ )}
+
setOpen(e)} /> + ))} + {shown.length === 0 && ( + + + +Curated collections+Explore by theme
++ {collections.map((c) => ( + + ))} +++ + + + + +++ + How to share+++ + Share what you made + + Ask your agent to share a project to the community. It opens a + pull request, and it shows up here once merged. + +++ + setLive(true) : undefined} + style={{ ...place, width: cover.w * scale, height: cover.h * scale }} + /> + ); +} + +/** A stage's width, which a grid's stretching columns set and only layout knows. */ +// oxlint-disable-next-line react/only-export-components +function useWidth() { + const ref = useRef
(null); + const [width, setWidth] = useState(0); + useLayoutEffect(() => { + const observer = new ResizeObserver(([entry]) => + setWidth(entry.contentRect.width), + ); + observer.observe(ref.current!); + return () => observer.disconnect(); + }, []); + return [ref, width] as const; +} + /** * A file card as Figma draws one: its cover on a grey stage. A link to its tab's address, which a * plain click opens as the tab instead. - * - * The cover is a picture of the board, `/__sp/shoot`'s, which the server draws once per edit, so - * a page of forty cards is forty images rather than forty documents. Where there is nothing to - * draw it, a build with no server or a machine without refkit, it is the board itself in a frame, - * sandboxed because a thumbnail has nothing to run. */ function Card(props: { href: string; @@ -85,18 +147,8 @@ function Card(props: { sub: string; count: string; }) { - const { cover, base } = props; - const stage = useRef (null); - const [stageW, setStageW] = useState(0); - const [live, setLive] = useState(!canvasIndex().served); - // The grid's columns stretch, so the stage's width is the card's and only known once laid out. - useLayoutEffect(() => { - const observer = new ResizeObserver(([entry]) => - setStageW(entry.contentRect.width), - ); - observer.observe(stage.current!); - return () => observer.disconnect(); - }, []); + const { cover } = props; + const [stage, stageW] = useWidth(); // The cover fills the stage: an element chosen as cover centred in it, a whole board from its // top, the way a page is read. Clamped so the board is under every pixel of the stage. const fit = cover && stageW > 0 && fitCover(cover.box, stageW, STAGE_H); @@ -108,8 +160,6 @@ function Card(props: { ? Math.min(0, Math.max(fit.top, STAGE_H - cover.h * fit.scale)) : 0, }; - const file = cover && `${base}board/${encodeURI(cover.path)}`; - const board = cover?.path.endsWith(".html"); return ( - {cover && - fit && - place && - (board && live ? ( - - ) : ( -+ )} {props.icon &&} @@ -184,6 +208,8 @@ export function HomePage(props: { newProject?: () => void; /** Lists the projects again, after one is deleted or its cover reset. */ reload: () => void; + /** Brings the Community tab forward (Community.tsx). */ + openCommunity: () => void; }) { const { projects, tabs } = props; const [sort, setSort] = useState
("edited"); @@ -226,6 +252,17 @@ export function HomePage(props: { A folder of canvases for your next app )} + img { + width: 48px; + height: 48px; + border-radius: 12px; + box-shadow: 0 0 0 1px var(--ds-gray-alpha-400); +} +.cm-head h3 { + margin: 0; + font-size: 20px; + font-weight: 600; +} +.cm-by { + display: inline-flex; + align-items: center; + gap: 6px; + margin-top: 2px; + color: var(--ds-gray-900); +} +.cm-by:hover { + color: var(--ds-gray-1000); +} +.cm-by img { + width: 18px; + height: 18px; + border-radius: 999px; +} +.cm-stats { + display: grid; + grid-template-columns: 1fr 1fr; + margin: 8px 0; + border: 1px solid var(--ds-gray-alpha-400); + border-radius: 12px; +} +.cm-stats div { + display: grid; + gap: 4px; + padding: 12px 14px; +} +.cm-stats div + div { + border-left: 1px solid var(--ds-gray-alpha-400); +} +.cm-stats b { + font-weight: 600; +} +.cm-tags { + display: flex; + flex-wrap: wrap; + gap: 6px; +} +.cm-tags button { + height: 28px; + padding: 0 12px; + border: 1px solid var(--ds-gray-alpha-400); + border-radius: 999px; + background: none; + color: var(--ds-gray-1000); + font: 13px var(--sp-sans); + cursor: pointer; +} +.cm-tags button:hover { + background: var(--ds-gray-100); +} +.cm-actions { + display: flex; + gap: 8px; + margin-top: auto; + padding-top: 12px; +} +.cm-close { + position: absolute; + top: 12px; + right: 12px; +} + +@media (max-width: 1180px) { + .cm-crow { + grid-template-columns: repeat(2, minmax(0, 1fr)); + } +} +@media (max-width: 760px) { + .cm-wrap { + padding: 0 16px; + } + .cm-grid { + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: 24px 12px; + } + .cm-avatar { + display: none; + } + .cm-crow { + grid-template-columns: 1fr; + } + .cm-submit, + .cm-footer { + flex-direction: column; + align-items: flex-start; + } +} + +/* The site's bar, on community.html only (community.tsx). */ +.cm-site { + position: sticky; + top: 0; + z-index: 5; + display: flex; + align-items: center; + justify-content: space-between; + height: 64px; + padding: 0 32px; + border-bottom: 1px solid var(--ds-gray-alpha-400); + background: color-mix(in srgb, var(--ds-background-100) 85%, transparent); + backdrop-filter: blur(12px); +} +.cm-site-brand { + white-space: nowrap; + display: flex; + align-items: center; + gap: 10px; + font-weight: 600; +} +.cm-site nav { + display: flex; + align-items: center; + gap: 20px; + color: var(--ds-gray-900); +} +.cm-site nav a:hover { + color: var(--ds-gray-1000); +} +.cm-site nav .cm-site-dl { + height: 32px; + padding: 0 12px; + color: var(--ds-background-100); +} +@media (max-width: 760px) { + .cm-site nav { + gap: 14px; + } + .cm-site { + padding: 0 16px; + } +} +.cm-dlg .cm-stage { + border-radius: 0; + box-shadow: none; +} diff --git a/canvas/src/communitySite.tsx b/canvas/src/communitySite.tsx new file mode 100644 index 00000000..ff989733 --- /dev/null +++ b/canvas/src/communitySite.tsx @@ -0,0 +1,48 @@ +import { StrictMode } from "react"; +import { createRoot } from "react-dom/client"; +import "@fontsource-variable/geist"; +import "@fontsource-variable/geist-mono"; +import "./home.css"; +import { loadCanvasIndex } from "./canvasIndex"; +import { LogoDiscord, LogoGithub } from "./geistIcons"; + +// The community as a page of the site, which serves this build's community.html at +// superproto.dev/community (the landing repo's Worker). The app has the same page as a tab +// (AppShell.tsx); here it has the site's bar over it instead, and Open is a link to the demo. +// +// The index first, as main.tsx does: the page reads it at module scope. +loadCanvasIndex(false) + .then(async () => { + const { CommunityPage } = await import("./Community"); + createRoot(document.getElementById("root")!).render( + + , + ); + }) + .catch((error) => { + document.getElementById("root")!.textContent = String(error); + }); diff --git a/canvas/src/geistIcons.tsx b/canvas/src/geistIcons.tsx index 5ec35373..6b275b1c 100644 --- a/canvas/src/geistIcons.tsx +++ b/canvas/src/geistIcons.tsx @@ -39,6 +39,16 @@ import { SidebarLeft as GSidebarLeft, Sparkles as GSparkles, TextTitle as GTextTitle, + ArrowRight as GArrowRight, + DesktopDevice as GDesktopDevice, + DeviceAlternate as GDeviceAlternate, + Globe as GGlobe, + GridSquare as GGridSquare, + Link as GLink, + MagnifyingGlass as GMagnifyingGlass, + PhoneDevice as GPhoneDevice, + Users as GUsers, + Window as GWindow, } from "geist-icons"; type IconProps = ComponentProps+++ + +
+ Super Prototyping
+
+
+ + ; @@ -76,3 +86,13 @@ export const RefreshCounterClockwise = at16(GRefreshCounterClockwise); export const SidebarLeft = at16(GSidebarLeft); export const Sparkles = at16(GSparkles); export const TextTitle = at16(GTextTitle); +export const ArrowRight = at16(GArrowRight); +export const DesktopDevice = at16(GDesktopDevice); +export const DeviceAlternate = at16(GDeviceAlternate); +export const Globe = at16(GGlobe); +export const GridSquare = at16(GGridSquare); +export const Link = at16(GLink); +export const MagnifyingGlass = at16(GMagnifyingGlass); +export const PhoneDevice = at16(GPhoneDevice); +export const Users = at16(GUsers); +export const Window = at16(GWindow); diff --git a/canvas/src/home.css b/canvas/src/home.css index eaecc8da..d69c3720 100644 --- a/canvas/src/home.css +++ b/canvas/src/home.css @@ -61,7 +61,7 @@ a { color: var(--ds-gray-1000); } /* The one action among the links out, in Geist's primary, the ground and the ink swapped. */ -button.home-tile i { +button.home-tile:not(.home-tile--community) i { background: var(--ds-gray-1000); box-shadow: none; color: var(--ds-background-100); diff --git a/canvas/vite.config.ts b/canvas/vite.config.ts index d68608a9..7f1db2f2 100644 --- a/canvas/vite.config.ts +++ b/canvas/vite.config.ts @@ -121,6 +121,8 @@ function canvasesSource(): Plugin { emit(file, fs.readFileSync(path.join(folder, file))); if (board.icon) emit("icon.png", fs.readFileSync(path.join(folder, "icon.png"))); + if (board.thumbnail) + emit("thumbnail.png", fs.readFileSync(path.join(folder, "thumbnail.png"))); for (const file of board.brand) { emit(file, fs.readFileSync(path.join(folder, file))); const thumb = await brandThumb(path.join(folder, file)); @@ -171,10 +173,11 @@ export default defineConfig({ // is a megabyte on its own and a warning nobody can act on is noise. chunkSizeWarningLimit: 4_000, rollupOptions: { - // Five pages. `index` and `home` are the window (shell.tsx), at a project's address and + // Six pages. `index` and `home` are the window (shell.tsx), at a project's address and // at its home page, which lists every project. `canvas` is the canvas in the window's // frame, `sheet` one canvas page's boards at full size, and `brand` the same page's brand - // material. Each is its own entry rather than a route inside the canvas, so reading one + // material, and `community` the community page as the site serves it (communitySite.tsx). + // Each is its own entry rather than a route inside the canvas, so reading one // as a web page does not download tldraw to do it. input: { index: "index.html", @@ -182,6 +185,7 @@ export default defineConfig({ canvas: "canvas.html", sheet: "sheet.html", brand: "brand.html", + community: "community.html", }, }, }, diff --git a/canvases/apple-app-store/thumbnail.png b/canvases/apple-app-store/thumbnail.png new file mode 100644 index 00000000..2c5548b2 Binary files /dev/null and b/canvases/apple-app-store/thumbnail.png differ diff --git a/canvases/apple-calendar/thumbnail.png b/canvases/apple-calendar/thumbnail.png new file mode 100644 index 00000000..1a98d439 Binary files /dev/null and b/canvases/apple-calendar/thumbnail.png differ diff --git a/canvases/apple-home-lock/thumbnail.png b/canvases/apple-home-lock/thumbnail.png new file mode 100644 index 00000000..6e6a520e Binary files /dev/null and b/canvases/apple-home-lock/thumbnail.png differ diff --git a/canvases/apple-icons/thumbnail.png b/canvases/apple-icons/thumbnail.png new file mode 100644 index 00000000..b557cb29 Binary files /dev/null and b/canvases/apple-icons/thumbnail.png differ diff --git a/canvases/apple-photos/thumbnail.png b/canvases/apple-photos/thumbnail.png new file mode 100644 index 00000000..51832539 Binary files /dev/null and b/canvases/apple-photos/thumbnail.png differ diff --git a/canvases/apple-settings/thumbnail.png b/canvases/apple-settings/thumbnail.png new file mode 100644 index 00000000..90d10858 Binary files /dev/null and b/canvases/apple-settings/thumbnail.png differ diff --git a/canvases/apple-wallet/thumbnail.png b/canvases/apple-wallet/thumbnail.png new file mode 100644 index 00000000..3cd45c52 Binary files /dev/null and b/canvases/apple-wallet/thumbnail.png differ diff --git a/canvases/chatgpt-ios/thumbnail.png b/canvases/chatgpt-ios/thumbnail.png new file mode 100644 index 00000000..de00a71a Binary files /dev/null and b/canvases/chatgpt-ios/thumbnail.png differ diff --git a/canvases/claude-ios/thumbnail.png b/canvases/claude-ios/thumbnail.png new file mode 100644 index 00000000..3c88722d Binary files /dev/null and b/canvases/claude-ios/thumbnail.png differ diff --git a/canvases/duolingo-ios/thumbnail.png b/canvases/duolingo-ios/thumbnail.png new file mode 100644 index 00000000..a9781afe Binary files /dev/null and b/canvases/duolingo-ios/thumbnail.png differ diff --git a/canvases/grok-ios/thumbnail.png b/canvases/grok-ios/thumbnail.png new file mode 100644 index 00000000..da999175 Binary files /dev/null and b/canvases/grok-ios/thumbnail.png differ diff --git a/canvases/instagram-ios/thumbnail.png b/canvases/instagram-ios/thumbnail.png new file mode 100644 index 00000000..5604632e Binary files /dev/null and b/canvases/instagram-ios/thumbnail.png differ diff --git a/canvases/luma-ios/thumbnail.png b/canvases/luma-ios/thumbnail.png new file mode 100644 index 00000000..df192062 Binary files /dev/null and b/canvases/luma-ios/thumbnail.png differ diff --git a/canvases/notion-ios/thumbnail.png b/canvases/notion-ios/thumbnail.png new file mode 100644 index 00000000..1af2ec71 Binary files /dev/null and b/canvases/notion-ios/thumbnail.png differ diff --git a/canvases/perplexity-ios/thumbnail.png b/canvases/perplexity-ios/thumbnail.png new file mode 100644 index 00000000..8ab776f9 Binary files /dev/null and b/canvases/perplexity-ios/thumbnail.png differ diff --git a/canvases/raycast-ios/thumbnail.png b/canvases/raycast-ios/thumbnail.png new file mode 100644 index 00000000..12398cfa Binary files /dev/null and b/canvases/raycast-ios/thumbnail.png differ diff --git a/canvases/snapaction-ios/thumbnail.png b/canvases/snapaction-ios/thumbnail.png new file mode 100644 index 00000000..a4edb57d Binary files /dev/null and b/canvases/snapaction-ios/thumbnail.png differ diff --git a/canvases/spotify-ios/thumbnail.png b/canvases/spotify-ios/thumbnail.png new file mode 100644 index 00000000..3c57c499 Binary files /dev/null and b/canvases/spotify-ios/thumbnail.png differ diff --git a/canvases/substack-ios/thumbnail.png b/canvases/substack-ios/thumbnail.png new file mode 100644 index 00000000..5a68d238 Binary files /dev/null and b/canvases/substack-ios/thumbnail.png differ diff --git a/canvases/tiktok-ios/thumbnail.png b/canvases/tiktok-ios/thumbnail.png new file mode 100644 index 00000000..16884144 Binary files /dev/null and b/canvases/tiktok-ios/thumbnail.png differ diff --git a/canvases/x-ios/thumbnail.png b/canvases/x-ios/thumbnail.png new file mode 100644 index 00000000..c70ca058 Binary files /dev/null and b/canvases/x-ios/thumbnail.png differ diff --git a/docs/2026-09-25-project-package.md b/docs/2026-09-25-project-package.md new file mode 100644 index 00000000..71794bbe --- /dev/null +++ b/docs/2026-09-25-project-package.md @@ -0,0 +1,378 @@ +# A project is the unit people share + +2026-09-25. Reviewed by two adversarial passes (correctness and security against the code; +scope against the rules in CLAUDE.md). What they changed is at the end. Phases 0 to 3 are +built; Phase 3's repo is ReScienceLab/super-prototyping-community. "What building it found" says where the build +went past the plan. + +Whatever someone shares, on the community page or anywhere else, is packed and uploaded as a +whole project. Nothing smaller is shared: a canvas that should travel alone is a project with +one canvas. This plan says what a package holds, how it is checked, and what has to be safe +before anyone opens a project someone else made. + +## Where the format stands + +A project is a folder under the projects directory (`2026-09-23-projects-folder-only.md`). +Everything a canvas shows is saved in the folder, and every reference inside it is relative +(`2026-09-24-canvas-content-on-disk.md`). That was designed with sharing in mind, and on the +seven projects on this machine it holds: + +- 295 `canvas.json` assets point at `./files/…`. One points at a sibling canvas's `files/`, + `../sandwich-video/files/…` from `kasra-design`. None is absolute, none is a data URI, and + none points at a file that is missing. +- `canvas.json` carries tldraw's `schemaVersion` and is migrated on load (`canvasContent.ts`). +- `project.json` stores the cover as a path, and falls back to the default if the path is gone. + +**It is sound as a working folder but not as a package.** Five gaps: + +1. **Nothing defines what a project is made of.** The server knows what it reads; the folder + holds whatever an agent left there. + + | Project | Size | What makes it big | + |---|---|---| + | Launch Video Studios | 5.5 GB | `sandwich-video/files/`, 2.1 GB of video | + | Super Prototyping Site | 485 MB | | + + About 730 MB across projects is `scratch/`. Project roots also hold `tools/`, `web/`, + `mockups/`, `.claude/`, `refs/`, `.DS_Store`, and a loose HTML presentation. +2. **A board is not safe to open outside the canvas.** Boards are arbitrary HTML with scripts. + On the canvas they are safe: `CanvasFileShapeUtil.tsx` renders them `srcDoc` with + `sandbox=""`, or `sandbox="allow-scripts"` without `allow-same-origin` for the inspector. + But `/board/ / .html` (`sp.ts:354`) serves the same HTML on the app's own origin + with no CSP. Two ways reach it: + - `BoardsSheet.tsx:133` frames every board unsandboxed. + - Any board link opened in a tab of its own. + + A script there sends `Sec-Fetch-Site: same-origin`. `sameOrigin()` (`sp.ts:48`), which + guards every `/__sp` route, accepts it. So the script can POST to `/__sp/agent/run` and have + the agent run shell commands on the machine, or write any project's files. This is true + today for any board an agent writes, not only for shared ones. +3. **Nothing names the format or the project.** `project.json` holds an optional `cover`, and + on some projects a `name` the agent wrote. + - It has no version, so a newer layout cannot be told apart from a broken one. + - A project has no id. Its identity is its folder name, which is also its address + (`/p/ /`). +4. **Broken or unsafe contents are tolerated.** + - `readJson` (`boards.ts`) warns and carries on when a JSON file will not parse. + - `boardIndex` follows symlinks on purpose (`layout.md`), and they could point anywhere. + - A name containing `#` or `?` is dropped from the canvas, with only a console warning. + + Tolerance is right for your own folder. At an upload it lets a broken or hostile project + through. +5. **Third-party material sits beside first-party work.** `ref-*.html`, `assets/refs/` and a + root `refs/` (screen recordings from `/__sp/projects/ref`) are captures of other people's + products. The repo's `.gitignore` keeps them out of Git; a zip of the folder would ship + them. + +## What others do + +Four surveys looked at design tools, code sandboxes, plugin registries and the pi coding agent. +What carries over: + +| From | Practice | Gap | +|---|---|---| +| Penpot `.penpot` | A rarely-changing *format* version on the package; each document keeps its own *data* version, migrated on import. | 3 | +| Obsidian, Blender, HACS | Identity is an `id` in the manifest, checked for collisions by a bot, never the folder or repo name. | 3 | +| Obsidian releases, npm `files` | An allowlist of what ships. Ignore files are the fallback, and are where leaks come from. | 1, 5 | +| CodePen, Observable, Claude Artifacts | Runnable user HTML only runs on an origin that is not the app's. Replit's 2019 XSS came from `allow-scripts` together with `allow-same-origin` on user content. | 2 | +| Blender, Bolt, CodePen | A stated size cap, enforced at upload. | 1 | +| excalidraw-libraries | Submit by PR: one folder per submission plus an index entry. CI checks, a person reviews. | — | +| pi packages | The folder layout is the manifest. A `pi` key in `package.json` is needed only to depart from the conventions. The gallery is unreviewed, and says so: "review third-party package source before installing it." | 1, 3 | + +Considered and not taken: + +- **A file inventory in the manifest (Penpot).** Our folder conventions already say what a + project holds, as pi's do, and `boardIndex` reads them. An inventory would be a second copy + of that, and could disagree with the folder. +- **"Scan, don't sandbox" (Obsidian, VS Code, pi).** Plugins need their powers, so a sandbox + would break them. Boards need none: they are self-contained by the rule in `layout.md`, so + isolating them costs almost nothing. For the same reason, PR review in Phase 3 is curation, + never the security control. Phase 0 is. +- **Content-addressed `files/` (Excalidraw).** Deduplication pays only once the same bytes are + shared twice, and renaming would touch every `canvas.json`. +- **Git LFS for large files.** It spends the community repo's bandwidth quota; the cap does the + job for now. + +## The plan + +### Phase 0: a board never runs on the app's origin + +This stands alone and ships first. It protects local users today. + +- **The server.** In the `/board` route, an `.html` or `.svg` response gets the header the + `/file` route already sends (`sp.ts:470`): + `Content-Security-Policy: sandbox allow-scripts allow-forms allow-popups allow-modals allow-downloads`. + + With no `allow-same-origin`, the document gets an opaque origin wherever it is loaded, + framed or top-level. Its requests then carry `Sec-Fetch-Site: cross-site`, which + `sameOrigin()` already refuses. Rasters and video under the same route cannot run script and + need nothing. +- **The hosted build.** `vite.config.ts` writes boards into `dist/board/` as static files, and + Cloudflare Pages runs no server. A `canvas/public/_headers` rule gives `/board/*` the same + header. It matters there too: the demo is proxied under `superproto.dev/demo/`, so the + landing page and the committed `ref-*` captures share its origin. +- **Links.** `CanvasLinkShapeUtil.tsx:273` passes `layout.json`'s `links[].url` to + `window.open` in the app's own frame. It opens only `http:` and `https:`. +- **Test** (`sp.test.ts`): a board and an SVG carry the CSP. A POST to `/__sp/agent/run` with + `Sec-Fetch-Site: cross-site` is refused; that is already true, and the test pins it. +- **Check by hand before merging:** + - Export to Figma, which reads `sheet.html`. + - `/__sp/shoot` and `refkit shoot` against a board URL. + - A board with Google Fonts. + - The inspector. + - A board that uses `localStorage`: it throws in an opaque origin, as it already does on the + canvas. + + What stops working is what this closes. It gets fixed the way the inspector already works, + with `postMessage`, not by loosening the sandbox. + +### Phase 1: `project.json` gets `format` and `id` + +```json +{ "format": 1, "id": "0b6d3c1e-…", "name": "Launch Video Studios", "cover": { "path": "…" } } +``` + +- **`format`: the version of the folder layout and of this app's own files** (`layout.json`, + `comments.json`, `project.json`). `canvas.json` keeps tldraw's schema version, which is + Penpot's second tier. + - A project with no `format` is `1`. That is not a fallback: every folder that exists today + is a format-1 folder, and this is the day the number starts. + - A project with a `format` above the app's is refused when opened, local or not, with a + message to update the app. An older app that opened it would half-understand it, and its + next save could lose what it did not understand. + - **`format` goes up rarely, only when an older app would misread the project.** Adding + something is not that: + - The app ignores files it does not know, and never deletes them. + - It ignores JSON keys it does not know, and writes them back unchanged. A write goes + through `withLayoutKey`, or reads the file and sets one key, as `project.json`'s cover + does, so this already holds. + - A new kind of content, a new key or a new file is therefore still format 1. Only a + change to what an existing thing means raises it. +- **`id`: a UUID, minted when New project makes the project** (`POST /__sp/projects` in + `projects.ts`). + - A project made earlier gets one from its first `sp pack`. Nothing is written on a GET, the + rule from `2026-09-22-agent-workspace.md`. + - The id is the project's identity for sharing only. The folder name stays the local + address, and routing and the store's keys do not change. +- `author` and `contributors` arrive with Phase 3, whose CI is what makes them true. + `license` and a fork's source are not added until a real submission shows where they + belong. +- `layout.md`'s section on `project.json` lists the two fields. That copy ships with the app, + and it is the one the agent reads. + +### Phase 2: `sp pack` + +`sp pack --check` validates and writes nothing. `sp pack -o ` also +copies what passes into ` `, as a folder: a PR adds a folder, so a zip has no reader yet. +- **`-o` also writes `thumbnail.png` at the package's root.** It is the project's cover, drawn + with headless Chrome at 2400×1260, an Open Graph image's 1200×630 twice over, so the same + file is the project's card and its link preview. + - It is Figma's `thumbnail.png` and Sketch's `previews/preview.png`: a package can be + browsed without the app, and the community page reads its card straight from it. + - It exists only in the package. In the project the cover stays a path, as + `2026-09-23-project-covers.md` decided, because a stored picture goes stale. +- It lives in `tools/sp_canvas.py` beside the other subcommands, because CI and the agent both + already run `sp`. +- The rules it applies partly repeat `boardIndex` and `cover.ts`, in a second language. That + drift is accepted until import in the app needs the same rules in TypeScript, which is the + second case that would justify sharing them. + +**What goes in.** A project's content is open-ended: boards today, and later videos, notes, +decks, or kinds of content nobody has made yet. So the package is defined by where things +sit, not by what they are: + +- **At the root**, only `project.json` (required), the Markdown documents (`*.md`), and + `canvases/`. Everything else there is left out: that is where agents leave tools, web + builds and loose drafts. +- **Inside `canvases/ /`, everything ships,** whatever its type, except the list below. + A new kind of content goes into a canvas folder and ships with no change to `sp pack` or to + `format`. `files/` ships whole, not only what a record points at. That keeps content that + something other than `canvas.json` refers to, now or later, and it also keeps a file one + canvas uses from another's folder. + +A folder with nothing but boards is a whole project, and so is one with nothing but a video. + +Left out anywhere, and listed in the report so the author sees it: +- `scratch/`, `ref-*`, `assets/refs/` and the root `refs/`: work in progress, and captures of + other people's products; +- dot files and dot folders; +- `comments.json`; +- `probes.json` and `crops.json`. These are the clone skill's measurement evidence. They + support a claim of fidelity to someone else's app, are not part of the work, and most + projects have none. + +This is a list of exclusions, where the surveys favoured a list of inclusions. The trade is +deliberate. An inclusion list leaks nothing, but it drops every new kind of content until +someone edits it. The exclusions here are few and known, and the checks below are what keep a +package safe, not the file types. + +**Checks.** Each check fails the pack; none warns and carries on: + +1. `project.json` parses and is an object, with a known `format` and a UUID `id`. +2. Every JSON file this app defines (`project.json`, `layout.json`, `canvas.json`) parses. + Other files are content, and are not read. +3. No symlinks. No path escapes the project after resolution. +4. **Every reference the app makes resolves to a file in the package:** `canvas.json` asset + `src`s, `layout.json` file entries, and the `project.json` cover. A new kind of reference + gets its check when the app starts making it. +5. `links[].url` in `layout.json` is `http:` or `https:`. +6. Names contain no `#` or `?`, do not start with a dot, and are NFC. macOS stores them + decomposed, and other systems do not re-normalise. +7. **Size: each file at most 50 MB, the whole at most 200 MB.** + - GitHub refuses files over 100 MB and warns from 50 MB, so 50 MB per file is the most a + PR can carry. + - That is a few minutes of 1080p video. A longer video goes on the canvas as a link to + where it is hosted, which the canvas already supports. + +Minting a missing `id` is the only write `sp pack` makes to the project. + +### Phase 3: community submission by PR + +The shape comes from excalidraw-libraries. The repo is +[ReScienceLab/super-prototyping-community](https://github.com/ReScienceLab/super-prototyping-community); +its `.github/community.py` is the check and the index, standard library only. + +- **A community repo** holds `projects/ /`, the output of `sp pack -o`, and an + `index.json` with one entry per project. +- **CI runs `sp pack --check`** on each changed project and checks that each `id` is either + new or already at that same path. A person reviews what passes, for quality. The review is + curation and promises nothing about safety; Phase 0 does that. + - The workflow runs on `pull_request_target` with read-only permissions: the base branch's + script checks the PR's files, and nothing from the PR is ever run. + - It installs `sp` from this repo at `vars.SP_REF`, else `main`. `SP_REF` names this + branch until `sp pack` reaches `main`; delete the variable then. +- **Every project names its people, and CI holds the names to the PR.** This is the Raycast + Store's model, the gallery closest to ours: its `package.json` names `author` and + `contributors` by handle, and its CI refuses an author it cannot tie to the submitter's + GitHub account. Excalidraw's `libraries.json` and Obsidian's registry name authors too, but + as unchecked text. Figma shows the publishing account and the co-creators it invites. + - `project.json` gains `author`, a GitHub login, and `contributors`, a list of them. The + names travel with the project, so the app can show them offline. Still format 1: they are + new keys. + ```json + { "format": 1, "id": "0b6d3c1e-…", "name": "…", "author": "octocat", "contributors": ["hubot"] } + ``` + - A PR that adds a project must be opened by its `author`. A PR that changes one must be + opened by its `author` or a contributor; anyone else is added to `contributors` by the same + PR, or CI fails it. That is proof of the GitHub account, which is all the authorship a + GitHub repo can prove, and it is enough. + - On merge, CI resolves each login to its numeric GitHub user id and writes both into + `index.json`. A login can be renamed and the id cannot, so the index finds the person + after a rename and corrects the login it shows. + - Avatars are `https://github.com/ .png`. Nothing is uploaded or stored. + - `sp pack -o` fills a missing `author` from `gh api user --jq .login` when `gh` is signed + in, and otherwise tells the person to set it. `--check` reports a missing `author` as a + problem, like a missing `id`. + - Links to a person's site or Twitter, which Excalidraw carries, wait until someone asks. +- **The community page** (`canvas/src/Community.tsx`) reads `index.json` from the repo's raw + files and lists those projects before the examples. It shows each `thumbnail.png` as an + image and never frames a board. A card shows the author's avatar and login, and the + contributors' avatars beside them. A shared project opens on GitHub until import exists. + The app shows the page as a tab; the site serves the hosted build's page at `/community`. + +## Later + +**Import** gets its own document when the app gets an import button. It has to: +- run every Phase 2 check on the way in, and refuse the whole package on any failure; +- stop extracting once the bytes actually written pass the cap, whatever the archive declares; +- refuse any entry whose path resolves outside the new folder; +- name the new folder from `name`, de-collided as New project does; +- ask the person, when the `id` is already in use, whether to replace that project or keep + both; +- tell the agent that the project, and its `gen.py`, came from someone else. + +A zip (`sp pack -o x.zip`) arrives with it, when something first hands out a download. + +**The examples move to the community repo.** The app ships every example in `canvases/` +inside every install: 411 MB as one project, twice the package cap. Once the community repo +takes projects, each example becomes a project there and the app downloads the ones a person +opens, so an install carries only the welcome canvas. Not now: it needs import first, and the +examples need a `project.json` each. `luma-ios` would not pass `sp pack` today: its layout +names four `w*-` walkthrough captures that are gitignored. + +Not planned: accounts, signing, hosting projects on superproto.dev, live collaboration, and +packing a single canvas. + +## Decided + +- **`gen.py` ships.** It is the canvas's source of truth, and a remix without it can only be + hand-edited. It is code, but the app never runs it. Import tells the agent whose code it is, + so the agent asks before running it. +- **`comments.json` does not ship.** Review threads can hold names and private remarks, and a + package shares the work, not its review. +- **Boards may load anything from the network, fonts above all.** A board may inline its fonts + or load them from any CDN, and the network is not closed with `connect-src` or `font-src`. + - All a board could send out is what someone types into the board itself. + - The opaque origin keeps the app, its files and the agent out of reach, and that is the + boundary. + - A font file inside the package counts against the caps like anything else. +- **The community repo stays small, so it is an ordinary GitHub repo.** Its CI is a GitHub + Actions workflow in that repo, owned by this project's maintainers. It runs `sp pack --check`, + checks that `thumbnail.png` is a 2400 × 1260 PNG, and fails a PR over the caps. It does not + check that the thumbnail is the cover `sp pack` would draw now: Chrome draws it a few pixels + differently on each machine, so a byte match would fail honest PRs. Its size is looked at + again if the repo passes 1 GB. +- **Licence and takedown.** One licence for the whole repo, CC BY 4.0 for the work and MIT for + the code in it such as `gen.py`, so no project needs a `license` key. The PR template has the + submitter confirm the work is theirs to share, and says the licence covers only their own + work, not the brands a clone copies. Takedown is an issue template and an email, answered + within 7 days, beside GitHub's own DMCA process. +- **Renaming a project sets only `name`,** when the app gets a rename. The folder is the + address agents, links and git history hold, and in the community repo a moved folder reads + as one project deleted and another added. + +## What building it found + +- **DNS rebinding.** Nothing checked the Host header, so a site that points its own name at + 127.0.0.1 was same-origin with the app and passed `sameOrigin()`, `/__sp/agent/run` + included. `projects.ts` now answers only to an IP address, `localhost` or `*.localhost`, in + front of every route. It is part of Phase 0 because it is the same boundary: a page from + elsewhere must not drive the app. +- **All of `/board` is sandboxed,** not only `.html` and `.svg`. The header does nothing to an + image or a video, and one rule is less to get wrong than a list of types. +- **A missing `project.json` is a format-1 project with no id,** as Phase 1 says, so `sp pack` + writes one rather than failing. A project made before today has none. +- **A reference to a file left out on purpose passes.** Clone layouts name their `ref-*` rows, + and the app already shows a missing board as missing. +- **The thumbnail is set like a book's cover,** on the canvas's ground: a spine down the + left edge, the app's `icon.png` where the canvas has one, the project's name in a serif and + its board count, and to the right the cover board whole with the boards as tall after it in + its row, as many as fit. Cropping to fill the frame, as a home card does, cuts a phone to its + top third. A per-project coloured backdrop was tried and dropped: the ground is what the + canvas already chose. +- **Every example has a `thumbnail.png` too,** drawn by `sp thumbnail