@autono/create-open-pages 0.1.0

package/template/.agents/skills/page-authoring/references/interactivity.md

@@ -0,0 +1,77 @@
+# Interactivity
+
+Pages are real React 18 components running in the browser, wrapped in
+`StrictMode`. Everything React can do is available; the constraints below
+keep pages preview-safe, export-safe, and inspectable.
+
+## State
+
+```tsx
+const [tab, setTab] = useState<'monthly' | 'yearly'>('monthly');
+
+<button
+  type="button"
+  onClick={() => setTab('yearly')}
+  aria-pressed={tab === 'yearly'}
+  className={tab === 'yearly' ? 'bg-slate-900 text-white' : 'text-slate-600'}
+>
+  Yearly
+</button>
+```
+
+- Keep state local and small: tabs, toggles, accordions, filters, form values.
+- Derive, do not duplicate: compute filtered lists with `useMemo` (or inline)
+  from the source array and the filter state.
+- Toggle/tab buttons carry `aria-pressed` or `role="tablist"` semantics;
+  disclosure buttons carry `aria-expanded` and `aria-controls`.
+
+## Forms
+
+- Real `<form>` with `onSubmit={(e) => { e.preventDefault(); … }}`.
+- Every input has a `<label htmlFor>` (or `aria-label`), a `name`, and a
+  sensible `type`/`inputMode`/`autoComplete`.
+- No backend exists in the workspace or the export. Either mirror submitted
+  values into local state ("Thanks, we'll be in touch"), or point the form at
+  a URL the user supplies (`action="https://formspree.io/…" method="post"`).
+  Never invent an endpoint.
+
+## Network and browser APIs
+
+- `fetch`, `localStorage`, `IntersectionObserver`, `matchMedia` are fine —
+  inside effects or handlers, with loading and error states.
+- Assume the exported page may run from `file://` or a static host with no
+  API: gate network features behind a URL the user supplied, and render
+  something meaningful without it.
+- Access `window`/`document` only inside `useEffect` or event handlers.
+  Module-top-level `window.innerWidth` breaks the module import and the
+  export build.
+
+## Effects and StrictMode
+
+- Effects run twice in development (StrictMode). Every subscription,
+  observer, timer, and listener must be cleaned up in the effect's return.
+- No side effects in render. No `Date.now()` / `Math.random()` in render for
+  layout-affecting values; seed them in state via a lazy initializer.
+
+## Progressive enhancement
+
+- Content must be visible with JavaScript disabled or before hydration: no
+  empty shells that only fill from an effect.
+- Hover-only affordances need a keyboard/touch equivalent.
+- Animations: `motion-safe:transition-*`; respect `prefers-reduced-motion`.
+
+## Routing inside a page
+
+- Simple multi-view pages: a `view` state and conditional rendering, with
+  `<a href="#section">` anchors for in-page navigation.
+- Hash routing is acceptable when the user asks for "pages" inside one export
+  (`window.location.hash`, read in an effect). Path-based routing needs a
+  host with rewrites — mention this to the user before choosing it.
+
+## Anti-patterns
+
+- ❌ `useEffect` to compute something derivable from props/state.
+- ❌ Fetching from an endpoint nobody set up.
+- ❌ `document.querySelector` to mutate the DOM React owns.
+- ❌ Global listeners without cleanup; timers that outlive the component.
+- ❌ Interactive `<div>`s. Use `<button>`, `<a>`, `<input>`, `<select>`.

package/template/.agents/skills/page-authoring/references/layout-and-responsive.md

@@ -0,0 +1,71 @@
+# Layout and responsive design
+
+The viewer previews every page at three widths — **Desktop** (the full
+viewport), **Tablet** (820px), and **Mobile** (390px). A page is done when all
+three look intentional. Tailwind is mobile-first: unprefixed utilities are the
+phone layout; `sm:` (640px), `md:` (768px), `lg:` (1024px), `xl:` (1280px)
+layer larger layouts on top.
+
+## Containers
+
+```tsx
+<section className="mx-auto max-w-6xl px-6 py-16 sm:py-24">…</section>
+```
+
+- Center content with `mx-auto max-w-*`; keep horizontal padding (`px-6`) so
+  text never touches the viewport edge on mobile.
+- Reading columns: `max-w-2xl` / `max-w-[65ch]` for prose. Marketing grids:
+  `max-w-5xl`–`max-w-7xl`.
+- Vertical rhythm: `py-16` between sections on mobile, `sm:py-24` on desktop.
+  Sections separate by space or a hairline (`border-t border-slate-200`), not
+  both.
+
+## Grids and stacks
+
+```tsx
+<div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+  {features.map((f) => <FeatureCard key={f.title} {...f} />)}
+</div>
+```
+
+- Default to a single column, add columns at `sm:`/`lg:`.
+- `flex flex-col gap-4 sm:flex-row sm:items-center` for header rows that must
+  stack on phones.
+- Use `gap-*`, not margins on children, for spacing inside grids and flex rows.
+
+## Navigation
+
+- Desktop nav links: `hidden sm:flex gap-8`. On mobile either show a compact
+  set of links, or a `<button aria-expanded>` that toggles a stacked menu with
+  `useState`. Never let a nav overflow horizontally.
+- Sticky headers: `sticky top-0 z-10 bg-white/90 backdrop-blur` — give them a
+  background so content does not bleed through.
+
+## Hero
+
+- Heading `text-4xl sm:text-6xl lg:text-7xl`, `leading-[1.05] tracking-tight`.
+- Constrain the heading (`max-w-3xl`) and the lede (`max-w-xl`) independently.
+- CTA row: `flex flex-col gap-3 sm:flex-row` so buttons stack on mobile.
+
+## Full-viewport pages (dashboards, app UIs)
+
+- Root: `min-h-screen` (not `h-screen`) so content can scroll.
+- Sidebars: `hidden lg:block w-64` plus a mobile alternative (top tabs or a
+  toggle). Content area: `min-w-0 flex-1` so tables and code blocks can shrink.
+- Wide content (tables, charts) scrolls inside its own `overflow-x-auto`
+  wrapper; the page body must never scroll horizontally.
+
+## Checklist
+
+- [ ] Mobile: no horizontal scrollbar, every grid stacks, headings shrink.
+- [ ] Tablet: two-column layouts where three would cramp.
+- [ ] Desktop: content is capped by a `max-w-*`, not stretched edge to edge.
+- [ ] Touch targets ≥ 40px tall on mobile (`py-2.5` on buttons and links).
+
+## Anti-patterns
+
+- ❌ Fixed pixel widths on layout containers (`w-[1200px]`).
+- ❌ `absolute` positioning for layout (fine for badges, overlays, decoration).
+- ❌ `h-screen` on scrolling pages; `overflow-hidden` on `body`/root.
+- ❌ Grids with no mobile fallback (`grid-cols-4` alone).
+- ❌ Text sized only for desktop (`text-7xl` with no smaller base).

package/template/.agents/skills/page-authoring/references/typography-and-color.md

@@ -0,0 +1,60 @@
+# Typography and color
+
+## Type scale (web)
+
+| Role | Tailwind | Notes |
+| --- | --- | --- |
+| Hero heading | `text-5xl sm:text-7xl font-bold leading-[1.02] tracking-tight` | one per page |
+| Page / section heading | `text-3xl sm:text-4xl font-bold tracking-tight` | |
+| Subsection | `text-xl font-semibold` | |
+| Lede | `text-lg sm:text-xl text-<muted>` | under the hero heading |
+| Body | `text-base leading-relaxed` (16px) | never smaller for running copy |
+| Secondary | `text-sm text-<muted>` | captions, metadata, table cells |
+| Eyebrow / label | `text-xs font-semibold uppercase tracking-[0.2em]` | above headings |
+| Code | `font-mono text-[0.9em]` with a subtle background | |
+
+- Line-height: tight (`leading-[1.05]`–`leading-tight`) for display sizes,
+  `leading-relaxed` (1.625) for body.
+- Measure: cap prose at `max-w-[65ch]` / `max-w-2xl`.
+- Numbers in tables and prices: `tabular-nums`.
+- Fonts: the system stack is the default and is fine. Register a display or
+  brand font only when the user names one — see `assets-and-fonts.md`.
+
+## Palette structure
+
+One page, one palette. Name the roles up front and reuse them literally:
+
+| Role | Light example | Dark example |
+| --- | --- | --- |
+| background | `bg-white` | `bg-[#0b0b10]` |
+| surface | `bg-slate-50` / `bg-white` cards with `border-slate-200` | `bg-white/[0.04]` with `border-white/10` |
+| text | `text-slate-900` | `text-white` |
+| muted | `text-slate-600` (never lighter than `slate-500` on white) | `text-white/60` |
+| accent | one hue, one shade for fills (`bg-indigo-600`) and one for text (`text-indigo-600`) | `bg-emerald-400 text-black` |
+| border | `border-slate-200` | `border-white/10` |
+
+- Define the palette as repeated utilities or as a small `const` map of class
+  strings when a page uses many surfaces. Do not build class names at runtime.
+- Accent is for actions and one highlight per screen. Two accents means no
+  accent.
+- Dark pages: prefer near-black (`#0b0b10`, `#111`) over pure black; lift
+  surfaces with translucent white (`bg-white/[0.03]`), not grey hex soup.
+
+## Contrast
+
+- Body text ≥ 4.5:1 against its background; large headings ≥ 3:1.
+- Muted text on white: `slate-500` is the floor. On dark: `white/60` is the
+  floor; `white/40` only for decorative metadata.
+- Accent text on white must be a 600+ shade (`indigo-600`, `emerald-700`).
+  `emerald-400` text on white fails.
+- Links inside prose: underline or a clearly different color, not color alone
+  at low contrast.
+
+## Anti-patterns
+
+- ❌ Body text under 16px, or `text-xs` for anything the user must read.
+- ❌ Three font families. Two is the ceiling (display + body).
+- ❌ Pure black on pure white for long text (`text-slate-900` on white reads
+  better); pure white on pure black for dark pages.
+- ❌ Gradient text, drop shadows, and glows on every heading. One flourish, once.
+- ❌ Palette drift: a new grey shade every section.

package/template/AGENTS.md

@@ -0,0 +1,31 @@
+# open-pages — Agent Guide
+
+You are authoring **web pages** in this repo. Every page is a React component rendered as a real web page — HTML JSX styled with Tailwind via `className`, with hooks, state, and browser APIs available. A page folder can hold an `index.html` instead when plain HTML is the better fit.
+
+## Hard rules
+
+- Put your page under `pages/<kebab-case-id>/`.
+- The entry is `pages/<id>/index.tsx` (or `pages/<id>/index.html`).
+- A page is its entry plus optional `components/`, `styles.css`, and `assets/` (images, fonts) inside its folder. Shared assets live in the root `assets/` folder (import via `@assets/...`).
+- Do **not** touch `package.json`, `open-pages.config.ts`, or other pages.
+- Do not add dependencies. Use only `react`, `react-dom`, and standard web APIs.
+
+## Which skill to use
+
+- **Drafting a new page** — use the `create-page` skill. It walks through scoping questions, structure, and hand-off.
+- **Applying inspector comments** (`@page-comment` markers in a page) — use the `apply-comments` skill.
+- **Creating or extracting a theme** — use the `create-theme` skill. Themes live as markdown under `themes/<id>.md` (with a `<id>.demo.tsx` preview) and are read by `create-page` before authoring.
+- **Resolving "this page" / "this element"** — when the user references the current page or selection without naming it, consult the `current-page` skill. It reads the dev server's `node_modules/.open-pages/current.json` to find which page and inspector-picked element they mean.
+- **Any other page edit** — read the `page-authoring` skill before writing. It is the technical reference for everything inside `pages/<id>/`: file contract, styling with Tailwind, layout and responsiveness, interactivity, assets and fonts, self-review checklist. `create-page` and `apply-comments` both defer to it for the *how*.
+
+Keep this file short: hard rules only. All deeper guidance lives in the skills above.
+
+## Updating skills
+
+The skills above are managed by `@autono/open-pages`. Do not edit them in place. To pull the latest versions:
+
+```
+npm run update
+```
+
+`npm run dev` will also detect drift on startup and offer to sync. `npx open-pages sync:skills --dry-run` previews changes without writing.

package/template/README.md

@@ -0,0 +1,76 @@
+# open-pages workspace
+
+Web pages as React components. Each page lives under `pages/<id>/index.tsx` and default-exports one component. The `@autono/open-pages` runtime handles Vite, React, Tailwind, the live preview, and the inspector — you just write the page.
+
+## Getting started
+
+```bash
+npm install
+npm run dev
+```
+
+Then open `http://localhost:5173`, edit `pages/getting-started/index.tsx`, or create a new page at `pages/<your-page>/index.tsx`. Each page previews at `http://localhost:5173/p/<id>`.
+
+## Scripts
+
+| Command | Description |
+| --- | --- |
+| `npm run dev` | Start the dev server with live preview and hot reload. |
+| `npm run build` | Build the whole workspace viewer as a static site. |
+| `npm run export` | Build pages into `export/<id>/`, one deployable folder per page. |
+| `npm run preview` | Preview the built workspace locally. |
+| `npm run sync:skills` | Sync the bundled agent skills into the workspace. |
+| `npm run update` | Update `@autono/open-pages` and sync skills. |
+
+## Authoring a page
+
+```tsx
+// pages/my-page/index.tsx
+import type { PageMeta } from '@autono/open-pages';
+
+export const meta: PageMeta = {
+  title: 'My page',
+  createdAt: '2026-08-28T00:00:00.000Z',
+};
+
+export default function MyPage() {
+  return (
+    <main className="mx-auto max-w-2xl px-6 py-24">
+      <h1 className="text-4xl font-bold tracking-tight">Hello</h1>
+      <p className="mt-4 text-slate-600">Tailwind via className, hooks, state, all of it.</p>
+    </main>
+  );
+}
+```
+
+A page is a real web page: Tailwind v4 utilities via `className` work out of the box, `import './styles.css'` for custom CSS, hooks and event handlers for interactivity. Put images and fonts under `pages/<id>/assets/` and import them; shared assets go in the root `assets/` folder and import via `@assets/...`.
+
+A folder holding an `index.html` (with sibling CSS/JS) instead of `index.tsx` works too. It is served as-is and exported the same way.
+
+See [`AGENTS.md`](./AGENTS.md) for the rules your agent follows.
+
+## The viewer
+
+- Toolbar toggles between desktop, tablet (820px), and mobile (390px) widths.
+- `i` toggles Inspect mode: click any element to see its source line and leave a comment for your agent.
+- **Open** shows the page by itself in a new tab.
+
+## Agent integration
+
+This workspace ships agent skills under `.agents/skills/` (symlinked into `.claude/skills/`). Ask your agent to "make a landing page for X" and the `create-page` skill takes over. Leave comments in Inspect mode and ask for `apply-comments` to iterate.
+
+## Config
+
+Optional `open-pages.config.ts` at the workspace root:
+
+```ts
+import type { OpenPagesConfig } from '@autono/open-pages';
+
+const openPagesConfig: OpenPagesConfig = {
+  port: 5173,
+};
+
+export default openPagesConfig;
+```
+
+Supported fields: `pagesDir`, `themesDir`, `assetsDir`, `port`, `base`, `allowedHosts`, `build`.

package/template/netlify.toml

@@ -0,0 +1,4 @@
+[[redirects]]
+  from = "/*"
+  to = "/index.html"
+  status = 200

package/template/open-pages.config.ts

@@ -0,0 +1,5 @@
+import type { OpenPagesConfig } from '@autono/open-pages';
+
+const openPagesConfig: OpenPagesConfig = {};
+
+export default openPagesConfig;

package/template/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "playground",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "open-pages dev",
+    "build": "open-pages build",
+    "export": "open-pages export",
+    "preview": "open-pages preview",
+    "sync:skills": "open-pages sync:skills",
+    "update": "open-pages update"
+  },
+  "dependencies": {
+    "@autono/open-pages": "^0.0.6",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "vite": "^5.4.10"
+  }
+}

package/template/pages/.folders.json

@@ -0,0 +1,4 @@
+{
+  "folders": [],
+  "assignments": {}
+}

package/template/pages/getting-started/index.tsx

@@ -0,0 +1,90 @@
+import type { PageMeta } from '@autono/open-pages';
+import { useState } from 'react';
+
+export const meta: PageMeta = {
+  title: 'Welcome to open-pages',
+  description: 'The web page framework built for agents.',
+  createdAt: '2026-08-28T00:00:00.000Z',
+};
+
+const steps = [
+  {
+    title: 'Describe',
+    body: 'Tell your agent what the page is. It runs /create-page and writes the React.',
+  },
+  {
+    title: 'Preview',
+    body: 'This workspace renders the real page in a real browser tab on every save.',
+  },
+  {
+    title: 'Annotate',
+    body: 'Press i, click anything, leave a note. It lands in the source as a comment marker.',
+  },
+  {
+    title: 'Ship',
+    body: 'Your agent runs /apply-comments. open-pages export writes a static folder you can deploy anywhere.',
+  },
+];
+
+export default function GettingStarted() {
+  const [active, setActive] = useState(0);
+
+  return (
+    <main className="min-h-screen bg-white text-slate-900 antialiased">
+      <section className="mx-auto max-w-3xl px-6 pt-24 pb-16">
+        <span className="text-xs font-semibold uppercase tracking-[0.2em] text-indigo-600">
+          open-pages
+        </span>
+        <h1 className="mt-4 text-5xl font-bold leading-[1.05] tracking-tight">
+          The web page framework built for agents
+        </h1>
+        <p className="mt-6 max-w-xl text-lg leading-relaxed text-slate-600">
+          This page is a React component at{' '}
+          <code className="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-[0.9em]">
+            pages/getting-started/index.tsx
+          </code>
+          . Your coding agent writes it, the workspace previews it live, and the export is plain
+          HTML, CSS, and JS.
+        </p>
+      </section>
+
+      <section className="mx-auto max-w-3xl px-6 pb-24">
+        <div className="grid gap-3 sm:grid-cols-4">
+          {steps.map((step, i) => (
+            <button
+              key={step.title}
+              type="button"
+              onClick={() => setActive(i)}
+              aria-pressed={active === i}
+              className={
+                active === i
+                  ? 'rounded-lg border border-indigo-600 bg-indigo-600 px-4 py-3 text-left text-white'
+                  : 'rounded-lg border border-slate-200 px-4 py-3 text-left transition-colors hover:border-slate-400'
+              }
+            >
+              <span className="block font-mono text-xs opacity-60">0{i + 1}</span>
+              <span className="mt-1 block font-semibold">{step.title}</span>
+            </button>
+          ))}
+        </div>
+        <p className="mt-6 min-h-[3.5rem] text-base leading-relaxed text-slate-700">
+          {steps[active].body}
+        </p>
+
+        <div className="mt-16 rounded-xl bg-slate-50 p-6">
+          <h2 className="text-sm font-semibold uppercase tracking-wider text-slate-500">
+            Try the loop
+          </h2>
+          <ol className="mt-3 space-y-2 text-slate-700">
+            <li>1. Change any text in this file and watch the preview update.</li>
+            <li>2. Switch the viewport to mobile in the toolbar. The layout is responsive.</li>
+            <li>
+              3. Ask your agent for something bigger: a landing page, a pricing table, a whole new
+              page with <code className="font-mono">/create-page</code>.
+            </li>
+          </ol>
+        </div>
+      </section>
+    </main>
+  );
+}

package/template/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["@autono/open-pages/env"]
+  },
+  "include": ["pages/**/*", "open-pages.config.ts"]
+}

package/template/vercel.json

@@ -0,0 +1,3 @@
+{
+  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
+}