@toonstrip/next 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @toonstrip/next
+
+`@toonstrip/react`'s `<ComicStrip>` behind an App-Router-safe `'use client'` boundary,
+plus `@toonstrip/next/server`'s `renderPlaceholder` for a real SSR PNG placeholder — no
+layout shift on hydration, and content visible with JavaScript disabled.
+
+Part of [toonstrip](https://github.com/dkdev24/toonstrip), a
+framework-embeddable comic-strip renderer. Docs, playground, and
+changelog: [toonstrip.danielkimdev.com](https://toonstrip.danielkimdev.com).
+
+## Install
+
+```
+npm install @toonstrip/next @toonstrip/cli @toonstrip/pack-comic-chat
+```
+
+`@toonstrip/cli` must be your app's own direct dependency, not only reachable
+transitively through `@toonstrip/next` — see
+[`docs/next.md`](https://github.com/dkdev24/toonstrip/blob/main/docs/next.md#native-dependency)
+for why, and for the `next.config.mjs` `serverExternalPackages` setting it also needs.
+
+## Use
+
+```tsx
+// app/page.tsx — a Server Component; no "use client" needed here
+import { ComicStrip } from "@toonstrip/next";
+import { renderPlaceholder } from "@toonstrip/next/server";
+import doc from "./my-strip.json";
+
+export default async function Page() {
+  const placeholder = await renderPlaceholder(doc, { width: 640 });
+  return (
+    <ComicStrip
+      document={doc}
+      packs={["/packs/comic-chat/"]}
+      placeholder={placeholder}
+    />
+  );
+}
+```
+
+Same props as `@toonstrip/react`'s `<ComicStrip>`. `renderPlaceholder` is a separate
+`@toonstrip/next/server` entry point (not the package root) because it pulls in
+`@toonstrip/cli`'s native canvas dependency — call it only from a Server Component or
+other server-only code.
+
+## Worked example
+
+See `examples/next-app` in the
+[repo](https://github.com/dkdev24/toonstrip/tree/main/examples/next-app) for a complete,
+runnable App Router app. Full field reference:
+[`docs/next.md`](https://github.com/dkdev24/toonstrip/blob/main/docs/next.md).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { ComicStrip } from "@toonstrip/react";
+export type { ComicStripProps, ComicStripPlaceholder } from "@toonstrip/react";

package/dist/index.js

@@ -0,0 +1,8 @@
+"use client";
+// The client-side, App-Router-safe boundary (dev plan §13.4): `@toonstrip/react`'s
+// `<ComicStrip>` uses `useRef`/`useEffect`, so it must be marked a Client
+// Component wherever a Server Component imports it. `packages/element`'s own
+// SSR guards (customElements/HTMLElement) are what keep the *module* safe to
+// import during the server render pass that still happens for a "use client"
+// tree; this directive is the separate, RSC-protocol half of that story.
+export { ComicStrip } from "@toonstrip/react";

package/dist/server.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Server-only SSR placeholder helper (dev plan §13.4). Reuses §8's existing
+ * headless-canvas render path (`packages/cli`, already published) to produce
+ * a real PNG of the strip at request/build time, ready to hand to
+ * `<ComicStrip placeholder>` as the light-DOM image it shows until client JS
+ * hydrates and paints the live canvas.
+ *
+ * A separate entry point ("@toonstrip/next/server", not the package root):
+ * `@toonstrip/cli` pulls in `@napi-rs/canvas`, a native Node addon that must
+ * never end up in a client bundle. Only import this from a Server Component
+ * or other server-only code.
+ *
+ * `@toonstrip/cli` is imported dynamically with `webpackIgnore` rather than
+ * statically: Next's `serverExternalPackages` opt-out is meant to stop it
+ * being bundled, but a workspace package reached through a symlinked,
+ * non-`node_modules` local package (`@toonstrip/cli`, here) doesn't reliably
+ * hit that path, and webpack then tries to statically bundle
+ * `@napi-rs/canvas`'s platform-detection `require()`s for every OS/arch and
+ * fails on the binary `.node` files. `webpackIgnore` leaves this import
+ * completely alone, so Node resolves and loads it normally at request time —
+ * from the *bundled output file's* location, though, so the consuming app
+ * must list `@toonstrip/cli` as its own direct dependency (not only reachable
+ * transitively through `@toonstrip/next`) for that resolution to succeed
+ * under pnpm's default strict `node_modules` layout.
+ */
+import type { ComicStripPlaceholder } from "@toonstrip/react";
+import type { ComicStripDocument } from "@toonstrip/schema";
+import type { RenderOptions } from "@toonstrip/cli";
+export declare function renderPlaceholder(doc: ComicStripDocument, options?: RenderOptions): Promise<ComicStripPlaceholder>;

package/dist/server.js

@@ -0,0 +1,10 @@
+export async function renderPlaceholder(doc, options = {}) {
+    const { renderDocument } = await import(/* webpackIgnore: true */ "@toonstrip/cli");
+    const { png, cssWidth, cssHeight } = await renderDocument(doc, options);
+    // The <img>'s width/height are CSS pixels (RenderResult.cssWidth/cssHeight),
+    // not the (possibly `scale`d-up) PNG's own pixel size — an `<img>` displays
+    // at its width/height attributes regardless of the file's actual pixel
+    // density, so using the PNG's raw pixel size here would render it 2x too
+    // large (the default `scale`) and shift layout on hydration.
+    return { src: `data:image/png;base64,${png.toString("base64")}`, width: cssWidth, height: cssHeight };
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@toonstrip/next",
+  "version": "0.1.0",
+  "description": "@toonstrip/react behind an App-Router-safe 'use client' boundary, plus a server-only SSR placeholder helper.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@toonstrip/cli": "workspace:*",
+    "@toonstrip/react": "workspace:*",
+    "@toonstrip/schema": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "toonstrip",
+    "comic",
+    "next",
+    "nextjs",
+    "ssr"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dkdev24/toonstrip.git",
+    "directory": "packages/next"
+  },
+  "homepage": "https://github.com/dkdev24/toonstrip#readme",
+  "bugs": "https://github.com/dkdev24/toonstrip/issues"
+}