p5.zine 0.0.1

package/.github/workflows/build.yml

@@ -0,0 +1,27 @@
+name: Build and Deploy
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '16'
+
+      - name: Install dependencies and build
+        run: |
+          npm install
+          npm run build

package/README.md

@@ -0,0 +1,263 @@
+# p5.zine
+
+p5.zine is a **browser‑first** library on top of p5.js for making printable zines. It creates five `p5.Graphics` pages (cover, one, two, three, back) and provides helpers for layout, export, and preview.
+
+> ✅ **Intended usage:** load via `<script>` tags (CDN or local file).  
+> ❌ **Not meant** to be imported as an ES module in bundlers.
+
+## Quick start (CDN, easiest)
+
+### p5 2.x
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/p5@2.2.0/lib/p5.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/p5.zine@1.0.1/dist/p5.zine.js"></script>
+<script>
+  function setup() {}
+  function draw() {
+    cover.background(255);
+    cover.text("Hello", 40, 60);
+
+    one.background(240);
+    if (one.mouseHere) {
+      one.ellipse(one.mouseX, one.mouseY, 40);
+    }
+  }
+</script>
+```
+
+### p5 1.x (legacy)
+
+```html
+<script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.11.1/p5.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/p5.zine@1.0.1/dist/p5.zine.legacy.js"></script>
+```
+
+## Table of contents
+
+- [Quick start (CDN, easiest)](#quick-start-cdn-easiest)
+- [Bundles (p5 2.x + 1.x)](#bundles-p5-2x--1x)
+- [Local dev / preview](#local-dev--preview)
+- [Pages](#pages)
+- [Configuration (window.zine)](#configuration-windowzine)
+- [Preview modes](#preview-modes)
+- [Mouse handling](#mouse-handling)
+- [Download background](#download-background)
+- [Page size vs. paper size](#page-size-vs-paper-size)
+- [Export](#export)
+- [Custom helpers (custom.js)](#custom-helpers-customjs)
+- [CDN usage (advanced)](#cdn-usage-advanced)
+- [Releases & versioning (maintainers)](#releases--versioning-maintainers)
+- [Architecture (1.x + 2.x addons)](#architecture-1x--2x-addons)
+- [Internal defaults](#internal-defaults)
+
+## Bundles (p5 2.x + 1.x)
+
+The build outputs two bundles:
+
+- `dist/p5.zine.js` → **p5 2.x** (`p5.registerAddon`)
+- `dist/p5.zine.legacy.js` → **p5 1.x** (`p5.prototype` + `registerMethod`)
+
+## Local dev / preview
+
+```bash
+npm run dev
+```
+
+Open:
+
+- `http://localhost:3000/test/index.html` (p5 2.x)
+- `http://localhost:3000/test/index.legacy.html` (p5 1.x)
+- `http://localhost:3000/test/compat.html` (side‑by‑side)
+
+Other scripts:
+
+```bash
+npm run build
+npm run preview
+npm run test
+```
+
+## Pages
+
+The library exposes five `p5.Graphics` pages:
+
+- `cover`
+- `one`
+- `two`
+- `three`
+- `back`
+
+Each page is its own canvas. In the default preview mode, these canvases are mounted in the DOM and scaled responsively.
+
+## Configuration (`window.zine`)
+
+Set options **before** `setup()` runs:
+
+```js
+window.zine = {
+  title: "My Zine",
+  author: "Your Name",
+  personalUrl: "https://example.com",
+  description: "Short description",
+
+  cam: true, // set false to disable webcam capture
+  frameRate: 10,
+  pixelDensity: 1,
+
+  preview: "pages", // "pages" (default) or "canvas"
+
+  downloadFormat: "png", // "png" (default) or "jpg"
+  downloadBackground: "#ffffff", // default white; use "transparent" for none
+
+  mouseClamp: true, // keep mouse within each page
+  mousePadding: 0,  // when mouseClamp is false, allow extra padding
+
+  // page size (single page)
+  pageWidth: "8.5in",
+  pageHeight: "11in",
+  // or pageSize: { width: "8.5in", height: "11in" }
+
+  // paper size (imposition)
+  // paperWidth: "11in",
+  // paperHeight: "17in",
+  // or paperSize: { width: "11in", height: "17in" }
+
+  // DPI + units (used for inches/cm/mm/pt conversions)
+  pageDPI: 96,
+  pageUnit: "in"
+};
+```
+
+## Preview modes
+
+- `preview: "pages"` (default) mounts each page canvas in the DOM and scales them responsively.
+- `preview: "canvas"` uses the legacy big preview canvas.
+
+## Mouse handling
+
+`page.mouseX/page.mouseY` are only populated when the pointer is over that page’s canvas.
+When the pointer is outside, they become `null` and `page.mouseHere` is `false`.
+
+## Download background
+
+Exports are rendered to an offscreen graphics buffer. By default a white background is applied so JPEGs are not black.
+Set `downloadBackground: "transparent"` to keep transparency (only works with PNG).
+
+## Page size vs. paper size
+
+### `zinePageSize(width, height, options)`
+Sets the **base size for each single page** (cover/back). Full spreads are 2× width.
+
+```js
+function setup() {
+  zinePageSize("8.5in", "11in", { dpi: 96 });
+}
+```
+
+### `zinePaperSize(width, height, options)`
+Sets the **full paper size** (imposition) and derives the page size:
+
+- `pageWidth = paperHeight / 4`
+- `pageHeight = paperWidth / 2`
+
+```js
+function setup() {
+  zinePaperSize("11in", "17in", { dpi: 300 });
+}
+```
+
+If you call both helpers, **the last call wins**.
+
+Supported units: `px`, `in`, `cm`, `mm`, `pt`. If you pass a number (or unitless string), it’s treated as pixels unless you set `pageUnit`.
+
+## Export
+
+### JPG / PNG
+
+The “download” button exports each page as an image. The extension matches `downloadFormat`.
+
+### PDF
+
+PDFs are generated using the imposition layout. The PDF page size is derived from your
+`pageDPI` / `paperDPI` so the PDF matches the paper dimensions instead of forcing Letter.
+
+## Custom helpers (custom.js)
+
+These helpers are available on both `p5` and `p5.Graphics`:
+
+- `Background`
+- `selfieBackground`
+- `rightCamera`
+- `randomLayout`
+- `gridLayout`
+- `glitchLayout`
+- `leftBackground`
+- `rightBackground`
+- `fullPage`
+- `leftPage`
+- `rightPage`
+- `textSet`
+- `textBox`
+
+## CDN usage (advanced)
+
+If you want a pinned version:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/p5.zine@1.0.1/dist/p5.zine.js"></script>
+```
+
+If you omit the version, CDN will serve the latest tag (which can include breaking changes).
+
+## Releases & versioning (maintainers)
+
+This project publishes to npm primarily to power CDN distribution. If you’re a maintainer:
+
+```bash
+npm version patch   # or minor / major
+npm run build
+npm publish
+```
+
+If you want automated releases, I can set up:
+
+- GitHub Actions for `npm publish` on tag
+- Auto‑generated changelog
+- Release notes from conventional commits
+
+## Architecture (1.x + 2.x addons)
+
+Core addon logic lives in:
+
+- `src/zine.js`
+- `src/custom.js`
+
+Adapters bridge to each runtime:
+
+- `src/adapters/p5-2.js` → uses `p5.registerAddon(...)` (p5 2.x)
+- `src/adapters/p5-1.js` → patches `p5.prototype` and maps lifecycles to `registerMethod(...)` (p5 1.x)
+
+Entry points:
+
+- `src/index.modern.js` → modern bundle
+- `src/index.legacy.js` → legacy bundle
+
+## Internal defaults
+
+```js
+const DEFAULTS = {
+  maxSinglePageWidth: 400,
+  rWidth: 198,
+  rHeight: 306,
+  pWidth: 800,
+  frameRate: 10,
+  pixelDensity: 1
+};
+```
+
+- `maxSinglePageWidth`: cap for the legacy preview canvas.
+- `rWidth` / `rHeight`: reference ratio used to compute page height from width.
+- `pWidth`: base width for a single page (pixels).
+
+If you want these exposed as public config, say the word and I’ll wire them up.

package/build.js

@@ -0,0 +1,77 @@
+const esbuild = require("esbuild");
+
+// Define the banner content
+const banner = `/* ==========================================================
+ *
+ * p5.zine
+ * Copyright (c) 2026 Munus Shih, Tuan Huang, Iley Cao
+ *
+ * Licensed under GNU General Public License.
+ * https://www.gnu.org/licenses
+ ===========================================================*/`;
+
+const args = new Set(process.argv.slice(2));
+const isWatch = args.has("--watch");
+const isServe = args.has("--serve");
+const isDev = args.has("--dev") || isWatch || isServe;
+
+const host = process.env.HOST || "localhost";
+const port = process.env.PORT ? Number(process.env.PORT) : 3000;
+
+const buildOptions = {
+  entryPoints: {
+    "p5.zine": "src/index.modern.js",
+    "p5.zine.legacy": "src/index.legacy.js",
+  },
+  bundle: true,
+  minify: !isDev,
+  sourcemap: isDev ? "inline" : false,
+  outdir: "dist",
+  legalComments: "inline",
+  banner: {
+    js: banner,
+  },
+  logLevel: "info",
+  color: true,
+  loader: {
+    ".html": "text",
+    ".css": "text",
+  },
+};
+
+async function run() {
+  if (!isWatch && !isServe) {
+    try {
+      await esbuild.build(buildOptions);
+      console.log("Build successful! 🎉");
+    } catch (error) {
+      console.error("❌ Build failed: ", error);
+      process.exit(1);
+    }
+    return;
+  }
+
+  const ctx = await esbuild.context(buildOptions);
+
+  if (isServe) {
+    const server = await ctx.serve({
+      servedir: ".",
+      host,
+      port,
+    });
+
+    console.log(
+      `Serving on http://${server.host}:${server.port} (open /test/index.html or /test/index.legacy.html)`,
+    );
+  }
+
+  if (isWatch) {
+    await ctx.watch();
+    console.log("Watching for changes...");
+  }
+}
+
+run().catch((error) => {
+  console.error("❌ Build failed: ", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "p5.zine",
+  "version": "0.0.1",
+  "description": "p5.zine is an open-sourced and friendly library for anyone curious about creative code and zine-making.",
+  "main": "main.js",
+  "scripts": {
+    "build": "node build.js",
+    "dev": "node build.js --watch --serve --dev",
+    "preview": "node build.js --serve --dev",
+    "test": "node build.js && node scripts/smoke-test.js",
+    "publish": "npm publish --access public"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "p5.js",
+    "zine",
+    "creative coding",
+    "zine-making",
+    "zine-coding"
+  ],
+  "author": "Munus Shih, Tuan Huang, Iley Cao",
+  "license": "GPL-3.0-only",
+  "devDependencies": {
+    "esbuild": "^0.24.0"
+  },
+  "dependencies": {
+    "jspdf": "^2.5.2"
+  }
+}

package/scripts/smoke-test.js

@@ -0,0 +1,53 @@
+const fs = require("fs");
+const path = require("path");
+const assert = require("assert");
+
+const root = path.resolve(__dirname, "..");
+const distModern = path.join(root, "dist", "p5.zine.js");
+const distLegacy = path.join(root, "dist", "p5.zine.legacy.js");
+const testModern = path.join(root, "test", "index.html");
+const testLegacy = path.join(root, "test", "index.legacy.html");
+
+function fileExists(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.F_OK);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+assert.ok(fileExists(distModern), "dist/p5.zine.js does not exist. Run npm run build first.");
+assert.ok(fileExists(distLegacy), "dist/p5.zine.legacy.js does not exist. Run npm run build first.");
+
+const modernStat = fs.statSync(distModern);
+const legacyStat = fs.statSync(distLegacy);
+assert.ok(modernStat.size > 0, "dist/p5.zine.js is empty.");
+assert.ok(legacyStat.size > 0, "dist/p5.zine.legacy.js is empty.");
+
+const modernContent = fs.readFileSync(distModern, "utf8");
+const legacyContent = fs.readFileSync(distLegacy, "utf8");
+assert.ok(
+  modernContent.includes("p5.zine"),
+  "dist/p5.zine.js does not include expected library banner/string."
+);
+assert.ok(
+  legacyContent.includes("p5.zine"),
+  "dist/p5.zine.legacy.js does not include expected library banner/string."
+);
+
+assert.ok(fileExists(testModern), "test/index.html is missing.");
+assert.ok(fileExists(testLegacy), "test/index.legacy.html is missing.");
+
+const testModernHtml = fs.readFileSync(testModern, "utf8");
+const testLegacyHtml = fs.readFileSync(testLegacy, "utf8");
+assert.ok(
+  testModernHtml.includes("../dist/p5.zine.js"),
+  "test/index.html does not reference ../dist/p5.zine.js."
+);
+assert.ok(
+  testLegacyHtml.includes("../dist/p5.zine.legacy.js"),
+  "test/index.legacy.html does not reference ../dist/p5.zine.legacy.js."
+);
+
+console.log("Smoke test passed ✅");

package/src/adapters/p5-1.js

@@ -0,0 +1,65 @@
+import { zineAddon } from "../zine.js";
+import { customAddon } from "../custom.js";
+
+function registerLegacyHooks(lifecycles) {
+  if (typeof p5 === "undefined") {
+    return;
+  }
+  if (typeof p5.prototype.registerMethod !== "function") {
+    return;
+  }
+
+  if (lifecycles.presetup) {
+    p5.prototype.registerMethod("beforeSetup", lifecycles.presetup);
+  }
+  if (lifecycles.postsetup) {
+    p5.prototype.registerMethod("afterSetup", lifecycles.postsetup);
+  }
+  if (lifecycles.predraw) {
+    p5.prototype.registerMethod("pre", lifecycles.predraw);
+  }
+  if (lifecycles.postdraw) {
+    p5.prototype.registerMethod("post", lifecycles.postdraw);
+  }
+  if (lifecycles.remove) {
+    p5.prototype.registerMethod("remove", lifecycles.remove);
+  }
+}
+
+function registerLegacyAddon() {
+  if (typeof p5 === "undefined") {
+    return;
+  }
+
+  const lifecycles = {};
+  zineAddon(p5, p5.prototype, lifecycles);
+  customAddon(p5, p5.prototype);
+  const originalInitZine = p5.prototype.initZine;
+  p5.prototype.initZine = function() {
+    if (typeof originalInitZine === "function") {
+      originalInitZine.call(this);
+    }
+
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    const pages = ["cover", "one", "two", "three", "back"];
+    pages.forEach((key) => {
+      if (this[key]) {
+        window[key] = this[key];
+      }
+    });
+
+    if (this.selfie) {
+      window.selfie = this.selfie;
+    }
+
+    if (this.all) {
+      window.all = this.all;
+    }
+  };
+  registerLegacyHooks(lifecycles);
+}
+
+registerLegacyAddon();

package/src/adapters/p5-2.js

@@ -0,0 +1,46 @@
+import { zineAddon } from "../zine.js";
+import { customAddon } from "../custom.js";
+
+function registerLegacyHooks(lifecycles) {
+  if (typeof p5 === "undefined") {
+    return;
+  }
+  if (typeof p5.prototype.registerMethod !== "function") {
+    return;
+  }
+
+  if (lifecycles.presetup) {
+    p5.prototype.registerMethod("beforeSetup", lifecycles.presetup);
+  }
+  if (lifecycles.postsetup) {
+    p5.prototype.registerMethod("afterSetup", lifecycles.postsetup);
+  }
+  if (lifecycles.predraw) {
+    p5.prototype.registerMethod("pre", lifecycles.predraw);
+  }
+  if (lifecycles.postdraw) {
+    p5.prototype.registerMethod("post", lifecycles.postdraw);
+  }
+  if (lifecycles.remove) {
+    p5.prototype.registerMethod("remove", lifecycles.remove);
+  }
+}
+
+function registerModernAddon() {
+  if (typeof p5 === "undefined") {
+    return;
+  }
+
+  if (typeof p5.registerAddon === "function") {
+    p5.registerAddon(zineAddon);
+    p5.registerAddon(customAddon);
+    return;
+  }
+
+  const lifecycles = {};
+  zineAddon(p5, p5.prototype, lifecycles);
+  customAddon(p5, p5.prototype);
+  registerLegacyHooks(lifecycles);
+}
+
+registerModernAddon();