uniweb 1.24.3 → 1.24.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.24.3",
3
+ "version": "1.24.5",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -42,14 +42,14 @@
42
42
  "prompts": "^2.4.2",
43
43
  "tar": "^7.5.21",
44
44
  "@uniweb/core": "~1.5.1",
45
- "@uniweb/semantic-parser": "~1.13.0",
46
45
  "@uniweb/schemas": "~1.6.7",
46
+ "@uniweb/semantic-parser": "~1.13.0",
47
47
  "@uniweb/content-writer": "~1.3.1"
48
48
  },
49
49
  "peerDependencies": {
50
+ "@uniweb/build": "~1.13.2",
50
51
  "@uniweb/semantic-parser": "~1.13.0",
51
- "@uniweb/content-reader": "~1.5.7",
52
- "@uniweb/build": "~1.13.2"
52
+ "@uniweb/content-reader": "~1.5.7"
53
53
  },
54
54
  "peerDependenciesMeta": {
55
55
  "@uniweb/build": {
@@ -28,6 +28,7 @@ You're building a *system* of section types, not individual pages. That's what m
28
28
 
29
29
  | Your situation | Start at |
30
30
  |---|---|
31
+ | Building a whole site for someone, content and code | **Part 3**, *Section format* through *Page organization*, then **Part 4**, *Where things go* through *Section wrapper*, *meta.js*, *Semantic theming*, *theme.yml*, *Fonts*. Read the rest when the site calls for it: *Records, queries and parametric pages* for a blog, *Forms* for a contact form |
31
32
  | New or nearly empty project | **Part 1**, then Part 4 |
32
33
  | Existing project, content task (pages, copy, colors, nav) | **Part 2**, then Part 3 |
33
34
  | Existing project, component task (new section type, restyle) | **Part 2**, then Part 4 |
@@ -2865,6 +2866,7 @@ uniweb inspect <path> # Show parsed content for a section or page (-
2865
2866
  uniweb snapshot # Compose site/public/preview.webp from the site; sets preview: if unset
2866
2867
  # needs `pnpm add -D -w @uniweb/snapshot` and Chrome or Edge
2867
2868
  uniweb snapshot --compare # Several looks on one sheet; take one with its flags + --save (site/snapshot.yml)
2869
+ uniweb snapshot --share # The first view as a 1200×630 link preview; sets seo.image if unset (--css arranges it)
2868
2870
 
2869
2871
  uniweb <command> --help # Per-command flags — no side effects. Prefer this over guessing.
2870
2872
  ```
package/partials/start.md CHANGED
@@ -19,47 +19,119 @@ that the pages pick by name. One project holds both. The `uniweb` CLI builds and
19
19
  and brings it into the Uniweb app, where the person can keep editing it visually.
20
20
  {{/if}}
21
21
 
22
- ## The person doesn't use a terminal
22
+ ## Run everything yourself
23
23
 
24
- Run every command yourself, and never ask them to run one. They do two things, in their
25
- browser: sign in, and pay when the site goes live. When a command prints an address to
26
- finish something in a browser, open it for them and say what it's for.
24
+ The person may never have used a terminal, and one who has still expects you to take this
25
+ from start to finish. Run every command yourself, and never ask them to run one. They do
26
+ two things, in their browser: sign in, and pay when the site goes live. When a command
27
+ prints an address to finish something in a browser, open it for them and say what it's
28
+ for.
27
29
 
28
30
  Uniweb needs Node.js 22.12 or later. If `node --version` shows an older one, install a
29
31
  current one yourself.
32
+
33
+ ## Work with them
34
+
35
+ - Ask only what you can't decide, in plain words. A first version they can react to tells
36
+ you more than a list of questions.
37
+ - Use what they give you: their words, their files, their current site. Don't invent facts
38
+ about them, and say which parts are placeholders.
39
+ {{#unless project}}
40
+ - Write the site in their language, and set `defaultLanguage` in `site.yml` to its code
41
+ (`defaultLanguage: es`). A site that doesn't say is taken to be in English.
42
+ {{/unless}}
43
+ - Keep anything they may want to change in markdown or in a param its `meta.js` declares,
44
+ not in a component's code. That is what they can edit in the app.
45
+ - Show them the site on their computer before you ask them to sign in.
30
46
  {{#unless project}}
47
+ {{#if nearby}}
48
+
49
+ ## A project is already here
50
+
51
+ {{#if oneNearby}}
52
+ {{nearby}}, in this folder, is a Uniweb project.
53
+ {{else}}
54
+ {{nearby}}, in this folder, are Uniweb projects.
55
+ {{/if}}
56
+ To work on one, go there and run `npx uniweb@latest start` again. Create a new one only
57
+ if they ask for it.
58
+ {{/if}}
31
59
 
32
60
  ## Create the project
33
61
 
62
+ {{#if otherProject}}
34
63
  ```bash
35
- npx uniweb@latest create <name> --template starter
64
+ npx uniweb@latest create <name> --template {{template}}
36
65
  cd <name>
37
66
  ```
38
67
 
39
68
  `<name>` is lowercase letters, digits and hyphens, and becomes the project's folder.
40
- `create` asks no questions when it runs without a terminal. `starter` has one generic
41
- section type and two short pages: a working example of each convention, to replace as
42
- you build. `--template none` is the same project without them.
43
- {{#if otherProject}}
69
+ `create` asks no questions when it runs without a terminal.
44
70
 
45
71
  Create it outside `{{otherProject}}`: that folder holds another project, and `create`
46
72
  does not make one inside it.
73
+ {{else}}
74
+ In a folder set aside for this site, even one that already holds their logo or photos:
75
+
76
+ ```bash
77
+ npx uniweb@latest create . --template {{template}}
78
+ ```
79
+
80
+ Anywhere else, give the project a folder of its own:
81
+
82
+ ```bash
83
+ npx uniweb@latest create <name> --template {{template}}
84
+ cd <name>
85
+ ```
86
+
87
+ `<name>` is lowercase letters, digits and hyphens. `create .` takes its name from the
88
+ folder, or from `--name <name>`, replaces a `README.md` or `.gitignore` already there, and
89
+ stops if any other file is in its way. `create` asks no questions when it runs without a
90
+ terminal.
91
+ {{/if}}
92
+
93
+ {{#if starter}}
94
+ `starter` has one generic section type and two short pages: a working example of each
95
+ convention, to replace as you build. `--template none` is the same project without them.
96
+ {{else if none}}
97
+ `none` is a project with no section types or pages: you build them all.
98
+ {{else}}
99
+ `{{template}}` is a working site: its section types are in `src/`, its sample content in
100
+ `site/`. Keep what fits, replace all the sample content with what they asked for, and
101
+ delete what they won't use. The code is theirs, so change whatever the site needs.
47
102
  {{/if}}
103
+
104
+ ## If their site is already in the Uniweb app
105
+
106
+ Bring it here instead of creating a project:
107
+
108
+ ```bash
109
+ npx uniweb@latest login --browser --personal # see "Sign them in", below
110
+ npx uniweb@latest site list # each site, with its id
111
+ npx uniweb@latest clone <site-uuid> <name>
112
+ cd <name>
113
+ npx uniweb@latest start
114
+ ```
115
+
116
+ A clone holds the site's content and uses its foundation by version: you can change its
117
+ pages, text and theme here, but not its section types.
48
118
  {{/unless}}
49
119
 
50
120
  ## Read the project's guide
51
121
 
52
122
  {{#if agents}}
53
123
  AGENTS.md, at the project's root, is the manual for this project and its version of
54
- Uniweb. Read its Part 0 before writing code: it says which parts your task needs.
124
+ Uniweb. It's long, so read its Part 0 before writing code, then the parts it names for
125
+ your task.
55
126
  {{else}}
56
127
  This project has no AGENTS.md, the manual for a Uniweb project. Write one with
57
- `npx uniweb update --agents-only`, then read its Part 0 before writing code: it says
58
- which parts your task needs.
128
+ `npx uniweb update --agents-only`, then read its Part 0 before writing code, and the parts
129
+ it names for your task.
59
130
  {{/if}}
60
131
 
61
132
  Uniweb's mistakes are quiet: an unknown section type or param builds fine and renders
62
- wrong. AGENTS.md says how to check.
133
+ wrong. AGENTS.md says how to check. Look at every page in a browser, wide and narrow,
134
+ before you call it ready.
63
135
  {{#if project}}
64
136
 
65
137
  ## Check what changed
@@ -94,8 +166,9 @@ npx uniweb login --browser --personal
94
166
  ```
95
167
 
96
168
  This opens their browser. If they're signed in to Uniweb there, it finishes on its own;
97
- otherwise they sign in, or sign up if they're new, and it waits up to five minutes. Never
98
- ask for a password or a token.
169
+ otherwise they sign in, or sign up if they're new. It waits up to five minutes, so give
170
+ the command that long or run it in the background, and run it again if it times out.
171
+ Never ask for a password or a token.
99
172
 
100
173
  `--personal` puts their sites in their own workspace. If they ask for one of their
101
174
  organizations instead, use `--org @<its handle>`.
@@ -108,14 +181,18 @@ npx uniweb publish --commit -m "<what you built>" # to take it live
108
181
  ```
109
182
 
110
183
  `push` sends the site and its foundation to their workspace, where they'll find it in
111
- the app. `publish` does the same and then takes the site live, so it needs no push
112
- first. `--commit` commits the site's content first: in a git repository, both send only
113
- what is committed.
184
+ the app, at https://uniweb.app. `publish` does the same and then takes the site live, so
185
+ it needs no push first. Take it live only when they ask: that's the step they pay for.
186
+ `--commit` commits the site's content first: in a git repository, both send only what is
187
+ committed.
114
188
 
115
189
  If the site needs paying for, `publish` prints an address instead of going live. Open
116
190
  it for the person, tell them it's where they pay, and run `publish` again once they're
117
191
  done.
118
192
 
193
+ When the site is in the app, tell them where to find it, and that it isn't live until they
194
+ ask you to take it live or publish it from the app.
195
+
119
196
  Once the site is in the app, it can be edited there at any time. Before you change it
120
197
  again, and before each push, run `npx uniweb status`: it says what changed in the app
121
198
  since your last push or pull, and what to run.
@@ -1185,7 +1185,7 @@ export async function checkLinkPreviews({ sitePath, siteName, issues }) {
1185
1185
  issues.push({ id, type: 'info', site: siteName, message })
1186
1186
  info(`[${id}] ${message}`)
1187
1187
  if (without.length < pages.length) listSome(without.map((p) => p.route))
1188
- log(` Set ${colors.green}seo.image${colors.reset} in site.yml — every page without one of its own shows it. A ${CARD.width}×${CARD.height} JPEG or PNG fills a card.`)
1188
+ log(` Set ${colors.green}seo.image${colors.reset} in site.yml — every page without one of its own shows it. A ${CARD.width}×${CARD.height} JPEG or PNG fills a card; ${colors.green}uniweb snapshot --share${colors.reset} makes one from the site.`)
1189
1189
  }
1190
1190
 
1191
1191
  // Each image once, with the pages that show it.
@@ -26,6 +26,11 @@
26
26
  * `preview:` is written only when site.yml has none, or holds something that is no
27
27
  * author's address — the token an older pull wrote there for a card image the app
28
28
  * generated. An address the author wrote is never replaced.
29
+ *
30
+ * `uniweb snapshot --share` is the other image: the site's link preview, recorded as
31
+ * `seo.image`. It is the first view of a page filling a 1200×630 image, with no frame
32
+ * and no look, and it shares nothing with the preview but finding the site. `--css`
33
+ * arranges the view for a picture, and its settings are `snapshot.yml`'s `share:` block.
29
34
  */
30
35
 
31
36
  import { spawn } from 'node:child_process'
@@ -45,6 +50,7 @@ import {
45
50
  SettingsError,
46
51
  mergeSettings,
47
52
  readSnapshotSettings,
53
+ saveShareSettings,
48
54
  saveSnapshotSettings
49
55
  } from '../utils/snapshot-settings.js'
50
56
  import { findWorkspaceRoot } from '../utils/workspace.js'
@@ -70,18 +76,20 @@ const SETTING_FLAGS = {
70
76
  '--scale': 'scale',
71
77
  '--quality': 'quality',
72
78
  '--hide': 'hide',
79
+ '--css': 'css',
73
80
  '--out': 'out'
74
81
  }
75
82
  const NUMBER_SETTINGS = ['gap', 'overlap', 'scale', 'quality']
76
83
  /** Flags that choose where the site comes from and what the run does. */
77
84
  const CONTROL_VALUE_FLAGS = ['--site', '--url']
78
- const CONTROL_BOOLEAN_FLAGS = ['--dev', '--no-build', '--no-set-preview', '--compare', '--save']
85
+ const CONTROL_BOOLEAN_FLAGS = ['--dev', '--no-build', '--no-set-preview', '--no-set-image', '--compare', '--save', '--share']
79
86
  const GLOBAL_FLAGS = ['--non-interactive', '--help', '-h']
80
87
  const ALL_FLAGS = [...Object.keys(SETTING_FLAGS), ...CONTROL_VALUE_FLAGS, ...CONTROL_BOOLEAN_FLAGS, ...GLOBAL_FLAGS]
81
88
  const LOOK_SETTINGS = ['gap', 'overlap', 'strip', 'side', 'frame']
82
89
 
83
90
  export const DEFAULT_OUTPUT = join('public', 'preview.webp')
84
91
  export const COMPARE_OUTPUT = join('.uniweb', 'snapshot', 'compare.webp')
92
+ export const SHARE_OUTPUT = join('public', 'share-card.png')
85
93
 
86
94
  class UsageError extends Error {}
87
95
 
@@ -120,7 +128,7 @@ export function parseSnapshotArgs(args = [], cwd = process.cwd()) {
120
128
  const key = SETTING_FLAGS[name]
121
129
  if (!key) control[camel(name)] = value
122
130
  else if (key === 'hide') settings.hide = [...(settings.hide ?? []), value]
123
- else if (key === 'out') settings.out = resolve(cwd, value)
131
+ else if (key === 'out' || key === 'css') settings[key] = resolve(cwd, value)
124
132
  else if (NUMBER_SETTINGS.includes(key)) {
125
133
  const number = Number(value)
126
134
  if (!Number.isFinite(number)) throw new UsageError(`\`${name}\` needs a number.`)
@@ -143,6 +151,17 @@ export function parseSnapshotArgs(args = [], cwd = process.cwd()) {
143
151
  if (control.compare && control.save) {
144
152
  throw new UsageError('`--save` keeps the look of a snapshot; choose a look from the sheet, then save that.')
145
153
  }
154
+ if (control.share) {
155
+ const look = ['layout', 'tone', ...LOOK_SETTINGS].find((key) => settings[key] !== undefined)
156
+ if (look) throw new UsageError(`\`--share\` fills the image with the first view, so it takes no \`--${look}\`.`)
157
+ if (control.compare) throw new UsageError('`--compare` shows looks of a preview image, and `--share` has none.')
158
+ if (control.noSetPreview) {
159
+ throw new UsageError('`--share` leaves `preview:` alone. To leave `seo.image` alone too, pass `--no-set-image`.')
160
+ }
161
+ } else {
162
+ if (settings.css) throw new UsageError('`--css` arranges a share image; it goes with `--share`.')
163
+ if (control.noSetImage) throw new UsageError('`--no-set-image` goes with `--share`; a preview image takes `--no-set-preview`.')
164
+ }
146
165
  return { settings, control, positionals }
147
166
  }
148
167
 
@@ -191,6 +210,16 @@ export function previewDecision(current, next) {
191
210
  return isAuthoredPreview(current) ? 'keep' : 'replace'
192
211
  }
193
212
 
213
+ /**
214
+ * What to do with site.yml's `seo.image` given the value we would write. An image the
215
+ * author named is never replaced: unlike `preview:`, nothing but an author writes this.
216
+ * @returns {'set'|'unchanged'|'keep'}
217
+ */
218
+ export function shareImageDecision(current, next) {
219
+ if (current === undefined || current === null || current === '') return 'set'
220
+ return current === next ? 'unchanged' : 'keep'
221
+ }
222
+
194
223
  /** The site the command applies to: named, else the one containing cwd, else the only one. */
195
224
  export function pickSite(sites, rootDir, { requested, cwd }) {
196
225
  if (requested) {
@@ -275,6 +304,124 @@ function fail(message, ...details) {
275
304
  process.exit(1)
276
305
  }
277
306
 
307
+ /** Put the site behind a URL: the one named, its dev server, or its build. */
308
+ async function siteBehindUrl({ control, site, siteDir, cwd, lib }) {
309
+ try {
310
+ if (control.url) {
311
+ return { url: control.url, label: control.url, close: async () => {} }
312
+ }
313
+ if (control.dev) {
314
+ console.error(`${DIM}→ starting the dev server for ${site.name}${RESET}`)
315
+ const dev = await lib.startDevServer(siteDir)
316
+ return { url: dev.url, label: `dev server (${dev.url})`, close: dev.close }
317
+ }
318
+ if (!control.noBuild) {
319
+ console.error(`${DIM}→ building ${site.name}${RESET}`)
320
+ await runBuild(siteDir)
321
+ }
322
+ const dist = join(siteDir, 'dist')
323
+ if (!existsSync(join(dist, 'index.html'))) {
324
+ fail(`No built site at ${relative(cwd, dist) || dist}.`, 'Run without `--no-build`, or build the site first.')
325
+ }
326
+ const server = await lib.serveDirectory(dist, { base: readSiteYml(siteDir).data.base })
327
+ return { url: server.url, label: 'the built site', close: server.close }
328
+ } catch (err) {
329
+ fail(err.message)
330
+ }
331
+ }
332
+
333
+ /** `uniweb snapshot --share`: the site's link preview image, recorded as `seo.image`. */
334
+ async function shareSnapshot({ flagSettings, fileShare, control, site, siteDir, rootDir, cwd }) {
335
+ const { css: cssFile, ...settings } = mergeSettings(fileShare, flagSettings)
336
+ let options
337
+ try {
338
+ options = libraryOptions(settings)
339
+ } catch (err) {
340
+ if (!(err instanceof UsageError)) throw err
341
+ fail(err.message)
342
+ }
343
+ options.output ??= join(siteDir, SHARE_OUTPUT)
344
+
345
+ let css = ''
346
+ if (cssFile) {
347
+ try {
348
+ css = readFileSync(cssFile, 'utf8')
349
+ } catch {
350
+ fail(`Cannot read the stylesheet at ${relative(cwd, cssFile) || cssFile}.`)
351
+ }
352
+ }
353
+
354
+ const lib = await loadSnapshotPackage([siteDir, rootDir])
355
+ if (!lib) {
356
+ fail(
357
+ '`uniweb snapshot` needs `@uniweb/snapshot`, which is not installed here.',
358
+ 'Add it as a dev dependency of the workspace:',
359
+ ` ${CYAN}${installHint(rootDir)}${RESET}`
360
+ )
361
+ }
362
+ if (typeof lib.shareCard !== 'function') {
363
+ fail('The installed `@uniweb/snapshot` predates `--share`.', 'Update it:', ` ${CYAN}${installHint(rootDir)}${RESET}`)
364
+ }
365
+ try {
366
+ lib.normalizeOptions({ ...options, canvas: options.canvas ?? lib.SHARE_CANVAS })
367
+ } catch (err) {
368
+ fail(err.message, `Check the flags${Object.keys(fileShare).length ? ` and ${SETTINGS_FILE}` : ''}.`)
369
+ }
370
+
371
+ const source = await siteBehindUrl({ control, site, siteDir, cwd, lib })
372
+ const onStep = (step) => {
373
+ if (step !== 'capture') return
374
+ const page = options.route && options.route !== '/' ? ` · ${options.route}` : ''
375
+ console.error(`${DIM}→ capturing ${source.label}${page}${RESET}`)
376
+ }
377
+
378
+ let result
379
+ try {
380
+ result = await lib.shareCard({ ...options, css, url: source.url, onStep })
381
+ } catch (err) {
382
+ await source.close().catch(() => {})
383
+ fail(err.message)
384
+ }
385
+ await source.close()
386
+
387
+ const shown = relative(cwd, options.output) || options.output
388
+ console.log(`${GREEN}✓${RESET} ${shown} ${DIM}(${result.width}×${result.height}, ${humanBytes(result.bytes)} — link preview image)${RESET}`)
389
+
390
+ if (control.save) {
391
+ const { saved } = saveShareSettings(siteDir, flagSettings)
392
+ const where = relative(cwd, join(siteDir, SETTINGS_FILE))
393
+ if (saved.length) console.log(` ${where}: ${CYAN}saved ${saved.join(', ')} under share${RESET}`)
394
+ else console.log(` ${DIM}${where}: nothing to save — pass the flags you want to keep.${RESET}`)
395
+ }
396
+
397
+ if (!siteDir || control.noSetImage) return
398
+
399
+ const value = previewValueFor(siteDir, options.output)
400
+ if (!value) {
401
+ console.log(` ${DIM}site.yml not changed: the image is outside ${join(site.path, 'public')}/, so it has no site path.${RESET}`)
402
+ return
403
+ }
404
+ const seo = readSiteYml(siteDir).data.seo
405
+ switch (shareImageDecision(seo?.image, value)) {
406
+ case 'set':
407
+ // Edited in place, its comments kept (`writeSiteConfig`) — and not at all when site.yml
408
+ // does not parse: that is said, and the file left as the author has it.
409
+ try {
410
+ writeSiteConfig(siteDir, { seo: { ...(seo && typeof seo === 'object' ? seo : {}), image: value } })
411
+ console.log(` site.yml: ${CYAN}seo.image: ${value}${RESET} ${DIM}(every page without its own shows it)${RESET}`)
412
+ } catch (err) {
413
+ console.log(` ${YELLOW}site.yml not changed:${RESET} ${DIM}${err.message}${RESET}`)
414
+ }
415
+ break
416
+ case 'unchanged':
417
+ console.log(` ${DIM}site.yml already has seo.image: ${value}${RESET}`)
418
+ break
419
+ case 'keep':
420
+ console.log(` ${YELLOW}site.yml keeps seo.image: ${seo.image}${RESET} ${DIM}— set it to ${value} to use this image.${RESET}`)
421
+ break
422
+ }
423
+ }
424
+
278
425
  export async function snapshot(args = []) {
279
426
  const cwd = process.cwd()
280
427
  let parsed
@@ -310,14 +457,21 @@ export async function snapshot(args = []) {
310
457
  // The site's saved look, under this run's flags. For a comparison, the file's
311
458
  // `out` names the preview image, not the sheet.
312
459
  let fileSettings = {}
460
+ let fileShare = {}
313
461
  if (siteDir) {
314
462
  try {
315
- fileSettings = readSnapshotSettings(siteDir).settings
463
+ const fromFile = readSnapshotSettings(siteDir)
464
+ fileSettings = fromFile.settings
465
+ fileShare = fromFile.share ?? {}
316
466
  } catch (err) {
317
467
  if (!(err instanceof SettingsError)) throw err
318
468
  fail(err.message)
319
469
  }
320
470
  }
471
+ if (control.share) {
472
+ await shareSnapshot({ flagSettings, fileShare, control, site, siteDir, rootDir, cwd })
473
+ return
474
+ }
321
475
  const base = { ...fileSettings }
322
476
  if (control.compare) delete base.out
323
477
  const merged = mergeSettings(base, flagSettings)
@@ -354,30 +508,7 @@ export async function snapshot(args = []) {
354
508
  }
355
509
  }
356
510
 
357
- // Put the site behind a URL.
358
- let source
359
- try {
360
- if (control.url) {
361
- source = { url: control.url, label: control.url, close: async () => {} }
362
- } else if (control.dev) {
363
- console.error(`${DIM}→ starting the dev server for ${site.name}${RESET}`)
364
- const dev = await lib.startDevServer(siteDir)
365
- source = { url: dev.url, label: `dev server (${dev.url})`, close: dev.close }
366
- } else {
367
- if (!control.noBuild) {
368
- console.error(`${DIM}→ building ${site.name}${RESET}`)
369
- await runBuild(siteDir)
370
- }
371
- const dist = join(siteDir, 'dist')
372
- if (!existsSync(join(dist, 'index.html'))) {
373
- fail(`No built site at ${relative(cwd, dist) || dist}.`, 'Run without `--no-build`, or build the site first.')
374
- }
375
- const server = await lib.serveDirectory(dist, { base: readSiteYml(siteDir).data.base })
376
- source = { url: server.url, label: 'the built site', close: server.close }
377
- }
378
- } catch (err) {
379
- fail(err.message)
380
- }
511
+ const source = await siteBehindUrl({ control, site, siteDir, cwd, lib })
381
512
 
382
513
  const onStep = (step) => {
383
514
  if (step === 'capture') {
@@ -17,44 +17,74 @@
17
17
  *
18
18
  * It is answered by the CLI that was invoked, never delegated to a project's own copy
19
19
  * (`STANDALONE_COMMANDS`): an older project CLI does not have it.
20
+ *
21
+ * ⭐ `--template <name>` names the template the guide creates the project from, so a prompt
22
+ * for a kind of site can say which one and the first command is still this read-only one.
23
+ * The name goes into the guide as given: `create`, which the guide tells the agent to run,
24
+ * is what says when a template does not exist.
20
25
  */
21
26
 
22
- import { existsSync, readFileSync } from 'node:fs'
27
+ import { existsSync, readdirSync, readFileSync } from 'node:fs'
23
28
  import { dirname, join } from 'node:path'
24
29
  import { fileURLToPath } from 'node:url'
25
30
  import Handlebars from 'handlebars'
31
+ import { readFlagValue } from '../utils/args.js'
26
32
  import { findUniwebWorkspace, findWorkspaceRoot } from '../utils/workspace.js'
27
33
  import { detectWorkspacePm, installCmd } from '../utils/pm.js'
28
34
 
29
35
  const PARTIAL = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'partials', 'start.md')
30
36
 
37
+ /**
38
+ * The Uniweb projects directly inside `cwd`, by folder name. `create <name>` puts a project
39
+ * one level below the folder an agent was opened in, and a later session opened in the same
40
+ * folder has to be told it is there rather than to create another.
41
+ *
42
+ * @param {string} cwd
43
+ * @returns {string[]}
44
+ */
45
+ function projectsIn(cwd) {
46
+ return readdirSync(cwd, { withFileTypes: true })
47
+ .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules')
48
+ .map((entry) => entry.name)
49
+ .filter((name) => findUniwebWorkspace(join(cwd, name)) === join(cwd, name))
50
+ .sort()
51
+ }
52
+
31
53
  /**
32
54
  * The guide, as Markdown, for a command run in `cwd`.
33
55
  *
34
56
  * Outside a project, `otherProject` names a workspace of another kind that holds `cwd`:
35
57
  * `create` refuses to make a project inside one, so the guide says to create it elsewhere.
36
58
  *
37
- * @param {{ cwd?: string }} [o]
59
+ * @param {{ cwd?: string, template?: string|null }} [o] - `template`: what to create the
60
+ * project from, `starter` when none is named
38
61
  * @returns {string}
39
62
  */
40
- export function startGuide({ cwd = process.cwd() } = {}) {
63
+ export function startGuide({ cwd = process.cwd(), template = null } = {}) {
41
64
  const root = findUniwebWorkspace(cwd)
42
- const template = Handlebars.compile(readFileSync(PARTIAL, 'utf8'), { noEscape: true })
43
- return template({
65
+ const nearby = root ? [] : projectsIn(cwd)
66
+ const name = template || 'starter'
67
+ const guide = Handlebars.compile(readFileSync(PARTIAL, 'utf8'), { noEscape: true })
68
+ return guide({
44
69
  project: !!root,
45
70
  root,
46
71
  // A project `create` makes has one; one already here may not.
47
72
  agents: root ? existsSync(join(root, 'AGENTS.md')) : true,
48
73
  otherProject: root ? null : findWorkspaceRoot(cwd),
74
+ nearby: nearby.map((folder) => `\`${folder}\``).join(', '),
75
+ oneNearby: nearby.length === 1,
76
+ template: name,
77
+ starter: name === 'starter',
78
+ none: name === 'none',
49
79
  install: installCmd(root ? detectWorkspacePm(root) : 'npm')
50
80
  })
51
81
  }
52
82
 
53
83
  /**
54
- * @param {string[]} [args] - none are read
84
+ * @param {string[]} [args] - `--template <name>`
55
85
  * @returns {Promise<{ exitCode: number }>}
56
86
  */
57
87
  export async function start(args = []) {
58
- console.log(startGuide())
88
+ console.log(startGuide({ template: readFlagValue(args, '--template') }))
59
89
  return { exitCode: 0 }
60
90
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-10-30T19:51:21.663Z",
3
+ "generatedAt": "2026-10-31T01:21:41.232Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
6
  "version": "1.6.7"
@@ -51,10 +51,10 @@
51
51
  "version": "1.13.0"
52
52
  },
53
53
  "@uniweb/snapshot": {
54
- "version": "1.1.1"
54
+ "version": "1.1.2"
55
55
  },
56
56
  "@uniweb/templates": {
57
- "version": "1.1.7"
57
+ "version": "1.1.8"
58
58
  },
59
59
  "@uniweb/theming": {
60
60
  "version": "1.2.1"
package/src/index.js CHANGED
@@ -1125,6 +1125,21 @@ async function main() {
1125
1125
 
1126
1126
  const prefix = getCliPrefix()
1127
1127
 
1128
+ // ⛔ A SECOND WORD IS REFUSED, not dropped. It is usually a template that lost its flag:
1129
+ // `npm create uniweb my-site --template docs` keeps `--template` for npm, and an agent that
1130
+ // got the starter instead of the docs template had nothing to tell it so.
1131
+ const words = args
1132
+ .slice(1)
1133
+ .filter((arg, i, all) => !arg.startsWith('-') && !(all[i - 1] ?? '').startsWith('-'))
1134
+ if (words.length > 1) {
1135
+ error(`Unexpected argument: ${words[1]}`)
1136
+ log(`\n${prefix} create takes one name. To start from a template:`)
1137
+ log(` ${colors.cyan}${prefix} create ${words[0]} --template ${words[1]}${colors.reset}`)
1138
+ log(`Through npm, which keeps flags for itself:`)
1139
+ log(` ${colors.cyan}npm create uniweb@latest ${words[0]} -- --template ${words[1]}${colors.reset}`)
1140
+ await exitWhenDrained(1)
1141
+ }
1142
+
1128
1143
  // In-place: derive the project name from the cwd basename (slugified),
1129
1144
  // or use --name when provided. Skip the interactive name prompt below.
1130
1145
  if (inPlace) {
@@ -1564,7 +1579,8 @@ ${colors.bright}Examples:${colors.reset}
1564
1579
  ${colors.cyan}${colors.bright}uniweb start${colors.reset} ${colors.dim}— How an AI agent begins a Uniweb site${colors.reset}
1565
1580
 
1566
1581
  ${colors.bright}Usage:${colors.reset}
1567
- npx uniweb@latest start Print the guide, in Markdown
1582
+ npx uniweb@latest start Print the guide, in Markdown
1583
+ npx uniweb@latest start --template docs The guide for a project from that template
1568
1584
 
1569
1585
  A short guide for an AI agent building a website for someone: create a
1570
1586
  project, read its AGENTS.md, run it, sign the person in, and bring the site
@@ -1604,6 +1620,7 @@ ${colors.cyan}${colors.bright}uniweb snapshot${colors.reset} ${colors.dim}— Co
1604
1620
  ${colors.bright}Usage:${colors.reset}
1605
1621
  uniweb snapshot [<site>] [options]
1606
1622
  uniweb snapshot --compare [options]
1623
+ uniweb snapshot --share [options]
1607
1624
 
1608
1625
  Opens the site in a headless Chrome, captures it, and composes the captures into
1609
1626
  one image: by default ${colors.bright}site/public/preview.webp${colors.reset}, recorded as ${colors.cyan}preview:${colors.reset} in site.yml
@@ -1637,6 +1654,15 @@ ${colors.bright}Choosing and keeping a look:${colors.reset}
1637
1654
  its flags (site/.uniweb/snapshot/compare.webp)
1638
1655
  --save Keep this run's flags in site/snapshot.yml, the site's defaults
1639
1656
 
1657
+ ${colors.bright}A link preview image:${colors.reset}
1658
+ --share The first view of the page filling a 1200×630 PNG, with no frame:
1659
+ ${colors.bright}site/public/share-card.png${colors.reset}, recorded as ${colors.cyan}seo.image${colors.reset} when site.yml has none.
1660
+ Takes --route, --size, --scale, --quality, --out, --hide and --save
1661
+ (under share: in site/snapshot.yml), and none of the look.
1662
+ --css <file> With --share: a stylesheet applied before capturing, to arrange the
1663
+ view for a picture
1664
+ --no-set-image With --share: write the image without touching site.yml
1665
+
1640
1666
  ${colors.bright}Options:${colors.reset}
1641
1667
  --site <name> The site (default: the one you are in, or the only one)
1642
1668
  --route <path> The page to capture (default: the home page)
@@ -5,6 +5,10 @@
5
5
  * It is the command's defaults for this site, and flags override it. Nothing else
6
6
  * reads it: the build, `push` and `pull` all leave a site's root files alone
7
7
  * unless they name them.
8
+ *
9
+ * The `share:` block holds the same for `uniweb snapshot --share`, the site's link
10
+ * preview image. The two share nothing: a preview's settings do not reach a share
11
+ * image, or the other way round.
8
12
  */
9
13
 
10
14
  import { existsSync, readFileSync, writeFileSync } from 'node:fs'
@@ -32,6 +36,9 @@ export const SETTING_KEYS = [
32
36
  'out'
33
37
  ]
34
38
 
39
+ /** What `share:` may hold, in the order they are written: a share image has no look. */
40
+ export const SHARE_SETTING_KEYS = ['route', 'size', 'scale', 'quality', 'hide', 'css', 'out']
41
+
35
42
  const HEADER = [
36
43
  '# How `uniweb snapshot` composes this site\'s preview image.',
37
44
  '# Flags override these; `uniweb snapshot <flags> --save` writes them here.',
@@ -41,8 +48,9 @@ const HEADER = [
41
48
  export class SettingsError extends Error {}
42
49
 
43
50
  /**
44
- * The settings in `<siteDir>/snapshot.yml`, or `{}` when there is none. `out` comes
45
- * back absolute, resolved against the site folder.
51
+ * The settings in `<siteDir>/snapshot.yml`, or `{}` when there is none, and its `share:`
52
+ * block as `share` when it has one. `out` and `css` come back absolute, resolved against
53
+ * the site folder.
46
54
  */
47
55
  export function readSnapshotSettings(siteDir) {
48
56
  const file = join(siteDir, SETTINGS_FILE)
@@ -60,7 +68,12 @@ export function readSnapshotSettings(siteDir) {
60
68
  }
61
69
 
62
70
  const settings = {}
71
+ let share
63
72
  for (const [key, value] of Object.entries(data)) {
73
+ if (key === 'share') {
74
+ share = readShareBlock(siteDir, value)
75
+ continue
76
+ }
64
77
  if (!SETTING_KEYS.includes(key)) {
65
78
  const suggestion = didYouMean(key, SETTING_KEYS)
66
79
  throw new SettingsError(
@@ -72,7 +85,28 @@ export function readSnapshotSettings(siteDir) {
72
85
  else if (key === 'out') settings.out = resolve(siteDir, String(value))
73
86
  else settings[key] = value
74
87
  }
75
- return { file, settings }
88
+ return share ? { file, settings, share } : { file, settings }
89
+ }
90
+
91
+ function readShareBlock(siteDir, block) {
92
+ if (block === null || block === undefined) return {}
93
+ if (typeof block !== 'object' || Array.isArray(block)) {
94
+ throw new SettingsError(`${SETTINGS_FILE}: \`share\` should be a list of settings, like \`route: /about\`.`)
95
+ }
96
+ const share = {}
97
+ for (const [key, value] of Object.entries(block)) {
98
+ if (!SHARE_SETTING_KEYS.includes(key)) {
99
+ const suggestion = didYouMean(key, SHARE_SETTING_KEYS)
100
+ throw new SettingsError(
101
+ `${SETTINGS_FILE}: \`share\` has an unknown setting \`${key}\`.` + (suggestion ? ` Did you mean \`${suggestion}\`?` : '')
102
+ )
103
+ }
104
+ if (value === null || value === undefined) continue
105
+ if (key === 'hide') share.hide = Array.isArray(value) ? value.map(String) : [String(value)]
106
+ else if (key === 'out' || key === 'css') share[key] = resolve(siteDir, String(value))
107
+ else share[key] = value
108
+ }
109
+ return share
76
110
  }
77
111
 
78
112
  /** Flags over the file. A gap or an overlap from the flags replaces either from the file. */
@@ -97,15 +131,39 @@ export function mergeSettings(fromFile = {}, fromFlags = {}) {
97
131
  export function saveSnapshotSettings(siteDir, fromFlags, fromFile = readSnapshotSettings(siteDir).settings) {
98
132
  const file = join(siteDir, SETTINGS_FILE)
99
133
  const merged = mergeSettings(fromFile, fromFlags)
100
- const ordered = {}
101
- for (const key of SETTING_KEYS) {
102
- if (merged[key] === undefined) continue
103
- ordered[key] = key === 'out' ? toSitePath(siteDir, merged.out) : merged[key]
104
- }
134
+ const ordered = orderedSettings(siteDir, merged, SETTING_KEYS)
135
+ // A preview's --save leaves the share image's settings as they are.
136
+ const { share } = readSnapshotSettings(siteDir)
137
+ if (share) ordered.share = orderedSettings(siteDir, share, SHARE_SETTING_KEYS)
105
138
  writeFileSync(file, HEADER + yaml.dump(ordered, { lineWidth: -1 }))
106
139
  return { file, saved: SETTING_KEYS.filter((key) => fromFlags[key] !== undefined) }
107
140
  }
108
141
 
142
+ /**
143
+ * Write the flags of a `--share` run into the file's `share:` block, over what it already
144
+ * holds, leaving the preview's settings as they are.
145
+ *
146
+ * @returns {{ file: string, saved: string[] }} the keys this run set
147
+ */
148
+ export function saveShareSettings(siteDir, fromFlags) {
149
+ const file = join(siteDir, SETTINGS_FILE)
150
+ const { settings, share = {} } = readSnapshotSettings(siteDir)
151
+ const ordered = orderedSettings(siteDir, settings, SETTING_KEYS)
152
+ ordered.share = orderedSettings(siteDir, mergeSettings(share, fromFlags), SHARE_SETTING_KEYS)
153
+ writeFileSync(file, HEADER + yaml.dump(ordered, { lineWidth: -1 }))
154
+ return { file, saved: SHARE_SETTING_KEYS.filter((key) => fromFlags[key] !== undefined) }
155
+ }
156
+
157
+ /** Settings as a file holds them: in a fixed order, with paths relative to the site. */
158
+ function orderedSettings(siteDir, settings, keys) {
159
+ const ordered = {}
160
+ for (const key of keys) {
161
+ if (settings[key] === undefined) continue
162
+ ordered[key] = key === 'out' || key === 'css' ? toSitePath(siteDir, settings[key]) : settings[key]
163
+ }
164
+ return ordered
165
+ }
166
+
109
167
  function toSitePath(siteDir, path) {
110
168
  const rel = relative(siteDir, path)
111
169
  return isAbsolute(rel) ? path : rel.split(sep).join('/')