learningfoundry 0.35.0__tar.gz → 0.37.0__tar.gz

{learningfoundry-0.35.0 → learningfoundry-0.37.0}/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.37.0] - 2026-04-29
+
+### Added
+
+- **First-class support for co-located image assets in lesson markdown.** Authors can now reference images directly from a lesson's markdown using either the markdown form (`![alt](path)`, `![alt](path "title")`) or the HTML form (`<img src="path">`); relative paths are resolved against the markdown file's own directory so authors keep images next to the markdown that uses them. `learningfoundry build` copies each unique image into `dist/static/content/<sha256[:12]>/<basename>` and rewrites the markdown URL to the absolute path `/content/<sha256[:12]>/<basename>` so it resolves at every nested route in the generated app. Same image referenced from N lessons → copied once (deduped by content hash). Absolute URLs (`https://`, `http://`, `//`, leading `/`, `data:` URIs) pass through unchanged so authors can mix CDN-hosted and co-located images. Image refs inside fenced code blocks (`` ``` `` or `~~~`) are left as literal text so code samples that demonstrate image syntax aren't silently rewritten. Missing images fail the build with the lesson location AND the expected on-disk path in the error message.
+  - New module `src/learningfoundry/asset_resolver.py` — pure function `resolve_markdown_assets(markdown, markdown_path) → (rewritten_markdown, list[Asset])`. Skips fenced code blocks, normalises query/fragment off the on-disk lookup, and dedupes by `dest_relative` (= content hash).
+  - `src/learningfoundry/resolver.py` — text-block resolution now invokes `resolve_markdown_assets()`; `ResolvedCurriculum` gained a top-level `assets: list[Asset]` field aggregated globally across modules/lessons (deduped by content hash).
+  - `src/learningfoundry/generator.py` — new `_copy_assets()` step copies each `Asset` into `output_dir/static/<dest_relative>` (idempotent on matching size, since the path is content-hashed). `_write_curriculum_json()` now strips `assets` from the serialised tree (the field carries on-disk `Path` objects and is consumed only by the generator).
+  - `_PRESERVED_PATHS` extended with `"static/content"` so previously-copied image assets survive a `learningfoundry build` re-run alongside `node_modules/`, `pnpm-lock.yaml`, `build/`, and `.svelte-kit/`.
+
+### Documentation
+
+- `README.md` — new "Images and assets" section in the Table of Contents with a worked example, the rules for relative vs. absolute URLs, the dedup-by-hash behaviour, and a note on how `static/content/` flows through to `build/content/` for static-export deployment.
+- `docs/specs/features.md` — Inputs section documents the image co-location convention; Outputs section documents the generated `static/content/<hash12>/<basename>` directory; FR-2 (Content Resolution) gained an "Image asset resolution" sub-requirement covering the regex strategy, passthrough rules, dedup, and error semantics.
+- `docs/specs/tech-spec.md` — added `asset_resolver.py` to Package Structure; added a new "asset_resolver.py — Markdown Image Asset Resolution" Key Component Design section; updated the `resolver.py` and `generator.py` sections to describe the asset hand-off; documented `Asset` and the `assets` field in Data Models.
+
+### Added (tests)
+
+- `tests/test_asset_resolver.py` — 19 cases covering relative-image resolution, subdirectory paths, title attributes, all five passthrough URL forms, missing-file error messages, dedup of identical content, hash separation of same-basename-different-bytes, HTML `<img>` (single + double quoted), fenced-code-block skipping for both `` ``` `` and `~~~`, query/fragment stripping, no-image no-op, and the `Asset.url_path` property.
+- `tests/test_resolver.py::TestTextBlockImageAssets` — 4 cases asserting that `resolve_curriculum()` populates `ResolvedCurriculum.assets`, rewrites lesson markdown to `/content/...` URLs, surfaces missing-image errors with the lesson location, and dedupes assets across lessons.
+- `tests/test_generator.py::TestImageAssetCopy` (4 cases) and `TestStaticContentPreserved` (2 cases) — verify that `Asset` records land on disk under `static/<dest_relative>`, that `assets` is stripped from `curriculum.json`, that absent assets don't create an empty `static/content/`, that rebuilds are idempotent on unchanged assets, and that an existing `static/content/` survives a rebuild.
+- `tests/test_smoke_sveltekit.py::test_co_located_image_reaches_build_output` — added a co-located `diagram.png` to `tests/fixtures/content/mod-01/` (referenced from `lesson-01.md`) and asserts the image lands at `build/content/<hash12>/diagram.png` after the full `learningfoundry build → pnpm install → pnpm build` smoke pipeline.
+
+## [0.36.0] - 2026-04-29
+
+### Changed
+
+- **`learningfoundry preview` is now the canonical "see your work" command.** Previously the post-build prompt and the README disagreed: the CLI told users to `cd dist && pnpm install && pnpm build` (a static export that exits without serving), while the README told them to run `learningfoundry preview`. Users following whichever doc they read first ended up with redundant work or wasted `pnpm install` invocations. The CLI's post-build prompt now consistently points at `learningfoundry preview` for every `DepState`, with `cd dist && pnpm build` mentioned only as the "for a static export to deploy" alternative.
+  - `src/learningfoundry/cli.py` — collapsed the three-branch `DepState` prompt into a single message: `Next: learningfoundry preview` (with a `⚠️  Dependencies changed …` line prepended in the `CHANGED` case so the user knows the upcoming `learningfoundry preview` will reinstall).
+  - `README.md` — Quick Start step 3 now combines build+preview into one `learningfoundry preview` invocation; the `learningfoundry preview` reference section explicitly notes that it serves the SvelteKit project from source via Vite (not the `pnpm build` static output) and now skips `pnpm install` when nothing has changed.
+
+### Performance
+
+- **`learningfoundry preview` no longer runs `pnpm install` on every invocation.** It now consults `check_dep_state(output_dir)` and skips the install step entirely when the state is `UNCHANGED` (every declared dep is already present in `node_modules/`). Subsequent `learningfoundry preview` runs after a content edit go straight to `pnpm run dev`, saving 5–30 s per cycle. The install still runs unconditionally on `FIRST_BUILD` and `CHANGED` states.
+  - `src/learningfoundry/pipeline.py::run_preview` — imports `DepState` and `check_dep_state`; logs `Dependencies up to date — skipping pnpm install.` when the state is `UNCHANGED`.
+
+### Added (tests)
+
+- `tests/test_cli.py::TestBuildNextStepsPrompt` — 3 cases asserting the new build prompt wording for `FIRST_BUILD`, `UNCHANGED`, and `CHANGED` states (each must say `Next: learningfoundry preview`; only `CHANGED` mentions the dep-change warning).
+- `tests/test_pipeline.py::TestRunPreviewSkipsInstall` — 3 cases verifying that `run_preview` invokes `pnpm install` on `FIRST_BUILD` and `CHANGED` but not on `UNCHANGED`, while always invoking `pnpm run dev`.
+
 ## [0.35.0] - 2026-04-29
 
 ### Fixed

{learningfoundry-0.35.0 → learningfoundry-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learningfoundry
-Version: 0.35.0
+Version: 0.37.0
 Summary: A curriculum engine that turns a YAML curriculum definition into a deployable SvelteKit learning application.
 Project-URL: Homepage, https://github.com/pointmatic/learningfoundry
 Project-URL: Repository, https://github.com/pointmatic/learningfoundry
@@ -45,6 +45,7 @@ A curriculum engine that turns a YAML curriculum definition into a deployable Sv
 - [Quick Start](#quick-start)
 - [CLI Reference](#cli-reference)
 - [Curriculum YAML Format](#curriculum-yaml-format)
+- [Images and assets](#images-and-assets)
 - [Configuration File](#configuration-file)
 - [Development Setup](#development-setup)
 
@@ -115,20 +116,17 @@ pip install "learningfoundry[quizazz]"
    # OK — curriculum is valid.
    ```
 
-3. **Build** the SvelteKit app:
-
-   ```bash
-   learningfoundry build
-   # Build complete → dist/
-   ```
-
-4. **Preview** locally (builds then starts a dev server):
+3. **Build and preview** locally:
 
    ```bash
    learningfoundry preview
    # Preview server started at http://localhost:5173
    ```
 
+   `learningfoundry preview` is the canonical "see your work" command — it builds the SvelteKit project, installs Node dependencies on first run (and again whenever they change), and starts a Vite dev server. On subsequent runs it skips the install step automatically.
+
+   `learningfoundry build` alone is also available if you want to generate the SvelteKit project without serving it (e.g. to inspect output, deploy a static export via `cd dist && pnpm build`, or wire into your own toolchain).
+
 ---
 
 ## CLI Reference
@@ -198,7 +196,9 @@ Options:
   --help                  Show this message and exit.
 ```
 
-Runs `pnpm install` and `pnpm run dev` in the generated project directory. Requires `pnpm` on `PATH`.
+Runs `learningfoundry build`, then `pnpm install` (skipped when every declared dependency is already present in `node_modules/`), then `pnpm run dev` in the generated project directory. Requires `pnpm` on `PATH`.
+
+This serves the SvelteKit project from source via Vite's dev server; it does **not** serve the static `pnpm build` output in `dist/build/`. For static deploys, use `cd dist && pnpm build` and host the resulting `dist/build/` directory on any static host.
 
 ---
 
@@ -264,6 +264,42 @@ curriculum:
 
 ---
 
+## Images and assets
+
+Lesson markdown can embed images directly. Place the image file alongside the markdown that uses it and reference it with a relative path:
+
+```
+content/
+└── mod-01/
+    ├── lesson-01.md
+    ├── diagram.png
+    └── figures/
+        └── architecture.svg
+```
+
+```markdown
+# Lesson One
+
+![Architecture diagram](figures/architecture.svg "Hover title")
+
+Here is a smaller inline diagram:
+
+<img src="diagram.png" alt="Diagram" />
+```
+
+**How it works:**
+
+- Relative URLs (`diagram.png`, `figures/architecture.svg`) are resolved against the markdown file's own directory. `learningfoundry build` copies each unique image into `dist/static/content/<sha256[:12]>/<basename>` and rewrites the markdown URL to the absolute path `/content/<sha256[:12]>/<basename>` so it resolves at every nested route in the generated app.
+- Both the markdown form (`![alt](path)`, `![alt](path "title")`) and the HTML form (`<img src="path">`) are recognised.
+- Absolute URLs (`https://`, `http://`, protocol-relative `//...`, root-absolute `/...`) and `data:` URIs pass through unchanged — useful for CDN-hosted assets you don't want copied into the build.
+- Image references inside fenced code blocks (` ``` ` or `~~~`) are left as literal text, so code samples that *demonstrate* image syntax aren't silently rewritten.
+- The same image referenced from N lessons is copied exactly once (deduped by content hash).
+- A missing image fails the build with the lesson location and the expected on-disk path in the error message.
+
+For production deployment to a CDN, just run `cd dist && pnpm build` — the `static/content/` tree gets bundled into the static export under `build/content/`, so deploying `build/` to any static host (Cloudflare Pages, Netlify, S3+CloudFront, …) serves the images at the same URLs the markdown references.
+
+---
+
 ## Configuration File
 
 An optional config file can set defaults for logging. The CLI always takes precedence.

{learningfoundry-0.35.0 → learningfoundry-0.37.0}/README.md

@@ -16,6 +16,7 @@ A curriculum engine that turns a YAML curriculum definition into a deployable Sv
 - [Quick Start](#quick-start)
 - [CLI Reference](#cli-reference)
 - [Curriculum YAML Format](#curriculum-yaml-format)
+- [Images and assets](#images-and-assets)
 - [Configuration File](#configuration-file)
 - [Development Setup](#development-setup)
 
@@ -86,20 +87,17 @@ pip install "learningfoundry[quizazz]"
    # OK — curriculum is valid.
    ```
 
-3. **Build** the SvelteKit app:
-
-   ```bash
-   learningfoundry build
-   # Build complete → dist/
-   ```
-
-4. **Preview** locally (builds then starts a dev server):
+3. **Build and preview** locally:
 
    ```bash
    learningfoundry preview
    # Preview server started at http://localhost:5173
    ```
 
+   `learningfoundry preview` is the canonical "see your work" command — it builds the SvelteKit project, installs Node dependencies on first run (and again whenever they change), and starts a Vite dev server. On subsequent runs it skips the install step automatically.
+
+   `learningfoundry build` alone is also available if you want to generate the SvelteKit project without serving it (e.g. to inspect output, deploy a static export via `cd dist && pnpm build`, or wire into your own toolchain).
+
 ---
 
 ## CLI Reference
@@ -169,7 +167,9 @@ Options:
   --help                  Show this message and exit.
 ```
 
-Runs `pnpm install` and `pnpm run dev` in the generated project directory. Requires `pnpm` on `PATH`.
+Runs `learningfoundry build`, then `pnpm install` (skipped when every declared dependency is already present in `node_modules/`), then `pnpm run dev` in the generated project directory. Requires `pnpm` on `PATH`.
+
+This serves the SvelteKit project from source via Vite's dev server; it does **not** serve the static `pnpm build` output in `dist/build/`. For static deploys, use `cd dist && pnpm build` and host the resulting `dist/build/` directory on any static host.
 
 ---
 
@@ -235,6 +235,42 @@ curriculum:
 
 ---
 
+## Images and assets
+
+Lesson markdown can embed images directly. Place the image file alongside the markdown that uses it and reference it with a relative path:
+
+```
+content/
+└── mod-01/
+    ├── lesson-01.md
+    ├── diagram.png
+    └── figures/
+        └── architecture.svg
+```
+
+```markdown
+# Lesson One
+
+![Architecture diagram](figures/architecture.svg "Hover title")
+
+Here is a smaller inline diagram:
+
+<img src="diagram.png" alt="Diagram" />
+```
+
+**How it works:**
+
+- Relative URLs (`diagram.png`, `figures/architecture.svg`) are resolved against the markdown file's own directory. `learningfoundry build` copies each unique image into `dist/static/content/<sha256[:12]>/<basename>` and rewrites the markdown URL to the absolute path `/content/<sha256[:12]>/<basename>` so it resolves at every nested route in the generated app.
+- Both the markdown form (`![alt](path)`, `![alt](path "title")`) and the HTML form (`<img src="path">`) are recognised.
+- Absolute URLs (`https://`, `http://`, protocol-relative `//...`, root-absolute `/...`) and `data:` URIs pass through unchanged — useful for CDN-hosted assets you don't want copied into the build.
+- Image references inside fenced code blocks (` ``` ` or `~~~`) are left as literal text, so code samples that *demonstrate* image syntax aren't silently rewritten.
+- The same image referenced from N lessons is copied exactly once (deduped by content hash).
+- A missing image fails the build with the lesson location and the expected on-disk path in the error message.
+
+For production deployment to a CDN, just run `cd dist && pnpm build` — the `static/content/` tree gets bundled into the static export under `build/content/`, so deploying `build/` to any static host (Cloudflare Pages, Netlify, S3+CloudFront, …) serves the images at the same URLs the markdown references.
+
+---
+
 ## Configuration File
 
 An optional config file can set defaults for logging. The CLI always takes precedence.

{learningfoundry-0.35.0 → learningfoundry-0.37.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "learningfoundry"
-version = "0.35.0"
+version = "0.37.0"
 description = "A curriculum engine that turns a YAML curriculum definition into a deployable SvelteKit learning application."
 readme = "README.md"
 license = "Apache-2.0"

{learningfoundry-0.35.0 → learningfoundry-0.37.0}/src/learningfoundry/__init__.py

@@ -1,4 +1,4 @@
 # Copyright 2026 Pointmatic
 # SPDX-License-Identifier: Apache-2.0
 
-__version__ = "0.35.0"
+__version__ = "0.37.0"

learningfoundry-0.37.0/src/learningfoundry/asset_resolver.py

@@ -0,0 +1,220 @@
+# Copyright 2026 Pointmatic
+# SPDX-License-Identifier: Apache-2.0
+"""Markdown image asset resolution.
+
+Scans a lesson's markdown source for image references (``![alt](path)``,
+``![alt](path "title")``, and the HTML ``<img src="path">`` form), copies
+the referenced files into the generated SvelteKit project's ``static/``
+directory under a content-keyed location (``content/<sha256[:12]>/<basename>``),
+and rewrites the markdown URLs to absolute paths that resolve at any
+SvelteKit route.
+
+Absolute URLs (``http://``, ``https://``, protocol-relative ``//``, root-
+absolute ``/...``) and ``data:`` URIs pass through unchanged so authors can
+mix CDN-hosted images with co-located ones.
+
+Fenced code blocks (``` ``` ``` ``` or ``~~~``) are skipped so literal
+``![](...)`` strings inside code samples are not treated as image refs.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from learningfoundry.exceptions import ContentResolutionError
+
+logger = logging.getLogger("learningfoundry.asset_resolver")
+
+# Markdown image: `![alt](url)` or `![alt](url "title")`.
+# - Group 1: alt text (kept verbatim in the rewrite)
+# - Group 2: URL (the bit we resolve and possibly rewrite)
+# - Group 3: optional title (kept verbatim, including its surrounding quotes)
+# We deliberately do not try to handle escaped parens inside the URL —
+# CommonMark's full grammar is out of scope for v0.37.0; the common case
+# is a plain relative path or an absolute URL with no whitespace.
+_MD_IMAGE_RE = re.compile(
+    r"""
+    !\[(?P<alt>[^\]]*)\]    # ![alt]
+    \(                       # opening paren
+    \s*
+    (?P<url>[^\s)]+)         # url (no whitespace, no closing paren)
+    (?:\s+(?P<title>"[^"]*"|'[^']*'))?  # optional "title" or 'title'
+    \s*
+    \)                       # closing paren
+    """,
+    re.VERBOSE,
+)
+
+# HTML <img src="..."> in either single- or double-quoted form.
+# We reuse the same `url` group name so the substitution callback is uniform.
+_HTML_IMG_RE = re.compile(
+    r"""
+    (?P<prefix><img\b[^>]*?\bsrc\s*=\s*)
+    (?P<quote>["'])
+    (?P<url>[^"']+)
+    (?P=quote)
+    """,
+    re.VERBOSE | re.IGNORECASE,
+)
+
+# A fenced code block opens with ≥3 backticks or ≥3 tildes at the start of a
+# line (allowing up to 3 leading spaces per CommonMark) and closes with the
+# same fence character at the same length-or-greater. We track the active
+# fence character to avoid closing a backtick fence with a tilde line.
+_FENCE_RE = re.compile(r"^ {0,3}(?P<fence>`{3,}|~{3,})")
+
+# URL schemes / leading characters that mean "leave this alone — it is not
+# a relative on-disk reference". Order matters only for clarity.
+_PASSTHROUGH_PREFIXES: tuple[str, ...] = (
+    "http://",
+    "https://",
+    "//",       # protocol-relative
+    "/",        # already root-absolute (already a SvelteKit static path)
+    "data:",    # inline data URI
+    "mailto:",
+    "tel:",
+)
+
+
+@dataclass(frozen=True)
+class Asset:
+    """A single asset that must be copied into the generated project.
+
+    Attributes:
+        source: Absolute path to the source file on disk.
+        dest_relative: Destination path relative to the generated project's
+            ``static/`` directory (e.g. ``"content/abc123def456/diagram.png"``).
+            Always uses forward slashes — this becomes a URL fragment too.
+    """
+
+    source: Path
+    dest_relative: str
+
+    @property
+    def url_path(self) -> str:
+        """Absolute URL path the rewritten markdown references."""
+        return "/" + self.dest_relative
+
+
+def resolve_markdown_assets(
+    markdown: str,
+    markdown_path: Path,
+) -> tuple[str, list[Asset]]:
+    """Find every relative image reference in ``markdown`` and resolve it.
+
+    Args:
+        markdown: Raw markdown source.
+        markdown_path: Filesystem path of the markdown file. Relative image
+            URLs are resolved against ``markdown_path.parent``.
+
+    Returns:
+        Tuple of ``(rewritten_markdown, assets)``. ``rewritten_markdown`` has
+        every relative image URL replaced with an absolute
+        ``/content/<hash>/<basename>`` path. ``assets`` is the deduped list of
+        source files to copy into the generated project (keyed on the content
+        hash, so two refs to the same bytes produce one ``Asset``).
+
+    Raises:
+        ContentResolutionError: A relative image reference points at a file
+            that does not exist, including the markdown file path in the
+            error message.
+    """
+    md_dir = markdown_path.parent
+    assets_by_dest: dict[str, Asset] = {}
+
+    def _make_asset(rel_url: str) -> Asset | None:
+        """Resolve ``rel_url`` to an Asset, or None if it should pass through.
+
+        Raises:
+            ContentResolutionError: The path resolves but the file is missing.
+        """
+        if _is_passthrough(rel_url):
+            return None
+        # Strip any fragment / query — image URLs rarely have them, but a
+        # `?cache=1` suffix should not become part of the on-disk lookup.
+        clean = rel_url.split("#", 1)[0].split("?", 1)[0]
+        if not clean:
+            return None
+        source = (md_dir / clean).resolve()
+        if not source.is_file():
+            raise ContentResolutionError(
+                f"image asset not found: `{clean}` "
+                f"(resolved to `{source}`, referenced from `{markdown_path}`)"
+            )
+        try:
+            digest = hashlib.sha256(source.read_bytes()).hexdigest()[:12]
+        except OSError as exc:
+            raise ContentResolutionError(
+                f"failed to read image asset `{source}` "
+                f"(referenced from `{markdown_path}`): {exc}"
+            ) from exc
+        dest_relative = f"content/{digest}/{source.name}"
+        asset = assets_by_dest.get(dest_relative)
+        if asset is None:
+            asset = Asset(source=source, dest_relative=dest_relative)
+            assets_by_dest[dest_relative] = asset
+        return asset
+
+    rewritten_lines: list[str] = []
+    in_fence = False
+    fence_char: str | None = None
+
+    for line in markdown.splitlines(keepends=True):
+        match = _FENCE_RE.match(line)
+        if match:
+            fence = match.group("fence")
+            if not in_fence:
+                in_fence = True
+                fence_char = fence[0]
+            elif fence[0] == fence_char and len(fence) >= 3:
+                in_fence = False
+                fence_char = None
+            rewritten_lines.append(line)
+            continue
+
+        if in_fence:
+            rewritten_lines.append(line)
+            continue
+
+        rewritten_lines.append(_rewrite_line(line, _make_asset))
+
+    rewritten = "".join(rewritten_lines)
+    return rewritten, list(assets_by_dest.values())
+
+
+def _is_passthrough(url: str) -> bool:
+    """Return True if ``url`` should not be treated as an on-disk reference."""
+    return any(url.startswith(p) for p in _PASSTHROUGH_PREFIXES)
+
+
+def _rewrite_line(
+    line: str,
+    make_asset: Callable[[str], Asset | None],
+) -> str:
+    """Rewrite all image refs in a single non-fenced line."""
+
+    def _md_sub(m: re.Match[str]) -> str:
+        url = m.group("url")
+        asset = make_asset(url)
+        if asset is None:
+            return m.group(0)
+        title = m.group("title")
+        title_part = f' {title}' if title else ''
+        return f'![{m.group("alt")}]({asset.url_path}{title_part})'
+
+    def _html_sub(m: re.Match[str]) -> str:
+        url = m.group("url")
+        asset = make_asset(url)
+        if asset is None:
+            return m.group(0)
+        quote = m.group("quote")
+        return f'{m.group("prefix")}{quote}{asset.url_path}{quote}'
+
+    line = _MD_IMAGE_RE.sub(_md_sub, line)
+    line = _HTML_IMG_RE.sub(_html_sub, line)
+    return line

{learningfoundry-0.35.0 → learningfoundry-0.37.0}/src/learningfoundry/cli.py

@@ -113,21 +113,17 @@ def build(
     from learningfoundry.generator import DepState, check_dep_state
 
     state = check_dep_state(output_dir)
-    if state is DepState.FIRST_BUILD:
-        click.echo("")
-        click.echo(f"Next: cd {output_dir} && pnpm install && pnpm build")
-        click.echo("  (or `pnpm dev` for a live-reloading dev server)")
-    elif state is DepState.CHANGED:
-        click.echo("")
+    click.echo("")
+    if state is DepState.CHANGED:
         click.echo(
             "⚠️  Dependencies changed since last install "
-            "(new packages in package.json)."
+            "(new packages in package.json) — `learningfoundry preview` "
+            "will reinstall."
         )
-        click.echo(f"   Run: cd {output_dir} && pnpm install && pnpm build")
-    else:
-        click.echo("")
-        click.echo(f"Next: cd {output_dir} && pnpm build")
-        click.echo("  (or `pnpm dev` for a live-reloading dev server)")
+    click.echo("Next: learningfoundry preview")
+    click.echo(
+        f"  (or `cd {output_dir} && pnpm build` for a static export to deploy)"
+    )
 
 
 # ---------------------------------------------------------------------------

{learningfoundry-0.35.0 → learningfoundry-0.37.0}/src/learningfoundry/generator.py

@@ -21,11 +21,17 @@ _TEMPLATE_DIR = Path(__file__).parent / "sveltekit_template"
 # are preserved across `learningfoundry build` re-runs so the user does not
 # have to `pnpm install` after every regen. Template files (package.json,
 # src/, static/, configs) are still refreshed every time.
+#
+# `static/content` is preserved so previously-copied image assets
+# (content-hashed under `static/content/<hash12>/<basename>`) survive a
+# rebuild — keeps `learningfoundry preview` snappy when only markdown
+# text changed and no new images were introduced.
 _PRESERVED_PATHS: tuple[str, ...] = (
     "node_modules",
     "pnpm-lock.yaml",
     "build",
     ".svelte-kit",
+    "static/content",
 )
 
 
@@ -83,6 +89,7 @@ def generate_app(
         )
 
     _atomic_copy(src, output_dir)
+    _copy_assets(resolved, output_dir)
     _write_curriculum_json(resolved, output_dir)
 
     logger.info("Generated SvelteKit project at: %s", output_dir)
@@ -174,13 +181,19 @@ def check_dep_state(output_dir: Path) -> DepState:
 
 
 def _write_curriculum_json(resolved: ResolvedCurriculum, output_dir: Path) -> None:
-    """Serialize ResolvedCurriculum to output_dir/static/curriculum.json."""
+    """Serialize ResolvedCurriculum to output_dir/static/curriculum.json.
+
+    The ``assets`` list is intentionally stripped — it carries on-disk
+    ``Path`` objects (which are not JSON-serialisable) and is consumed only
+    by the generator's asset-copy step, never by the SvelteKit frontend.
+    """
     static_dir = output_dir / "static"
     static_dir.mkdir(parents=True, exist_ok=True)
 
     curriculum_json = output_dir / "static" / "curriculum.json"
     try:
         data = dataclasses.asdict(resolved)
+        data.pop("assets", None)
         curriculum_json.write_text(
             json.dumps(data, indent=2, ensure_ascii=False) + "\n",
             encoding="utf-8",
@@ -191,3 +204,41 @@ def _write_curriculum_json(resolved: ResolvedCurriculum, output_dir: Path) -> No
         ) from exc
 
     logger.debug("Wrote curriculum.json (%d bytes)", curriculum_json.stat().st_size)
+
+
+def _copy_assets(resolved: ResolvedCurriculum, output_dir: Path) -> None:
+    """Copy each ``Asset`` to ``output_dir/static/<dest_relative>``.
+
+    Idempotent: a destination file whose size matches the source is left
+    untouched. Because ``dest_relative`` is content-hashed
+    (``content/<sha256[:12]>/<basename>``), a matching size on a path with a
+    matching hash implies matching content — re-copying would be wasted I/O.
+    """
+    if not resolved.assets:
+        return
+
+    static_dir = output_dir / "static"
+    static_dir.mkdir(parents=True, exist_ok=True)
+
+    copied = 0
+    skipped = 0
+    for asset in resolved.assets:
+        dest = static_dir / asset.dest_relative
+        try:
+            if dest.is_file() and dest.stat().st_size == asset.source.stat().st_size:
+                skipped += 1
+                continue
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(asset.source, dest)
+            copied += 1
+        except OSError as exc:
+            raise GenerationError(
+                f"Failed to copy image asset `{asset.source}` "
+                f"to `{dest}`: {exc}"
+            ) from exc
+
+    logger.info(
+        "Copied %d image asset(s) into static/ (%d already up to date).",
+        copied,
+        skipped,
+    )

{learningfoundry-0.35.0 → learningfoundry-0.37.0}/src/learningfoundry/pipeline.py

@@ -133,8 +133,11 @@ def run_preview(
 ) -> None:
     """Build then launch a local preview server.
 
-    Runs ``run_build()``, then ``pnpm install`` and ``pnpm run dev --port``
-    in the generated project directory.
+    Runs ``run_build()``, then ``pnpm install`` (only when needed) and
+    ``pnpm run dev --port`` in the generated project directory. The install
+    step is skipped when ``check_dep_state(output_dir)`` reports
+    ``DepState.UNCHANGED`` — i.e. every dependency declared in the
+    generated ``package.json`` is already present in ``node_modules/``.
 
     Args:
         curriculum_path: Path to the curriculum YAML file.
@@ -150,6 +153,7 @@ def run_preview(
         GenerationError: If build or pnpm commands fail.
     """
     from learningfoundry.exceptions import GenerationError
+    from learningfoundry.generator import DepState, check_dep_state
 
     run_build(
         curriculum_path,
@@ -161,17 +165,21 @@ def run_preview(
         generator=generator,
     )
 
-    logger.info("Installing Node dependencies in %s", output_dir)
-    result = subprocess.run(
-        ["pnpm", "install"],
-        cwd=output_dir,
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode != 0:
-        raise GenerationError(
-            f"`pnpm install` failed in `{output_dir}`:\n{result.stderr}"
+    state = check_dep_state(output_dir)
+    if state is DepState.UNCHANGED:
+        logger.info("Dependencies up to date — skipping pnpm install.")
+    else:
+        logger.info("Installing Node dependencies in %s", output_dir)
+        result = subprocess.run(
+            ["pnpm", "install"],
+            cwd=output_dir,
+            capture_output=True,
+            text=True,
         )
+        if result.returncode != 0:
+            raise GenerationError(
+                f"`pnpm install` failed in `{output_dir}`:\n{result.stderr}"
+            )
 
     logger.info("Starting dev server on port %d", port)
     subprocess.run(

{learningfoundry-0.35.0 → learningfoundry-0.37.0}/src/learningfoundry/resolver.py

@@ -8,6 +8,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+from learningfoundry.asset_resolver import Asset, resolve_markdown_assets
 from learningfoundry.exceptions import ContentResolutionError
 from learningfoundry.integrations.protocols import (
     ExerciseProvider,
@@ -63,6 +64,11 @@ class ResolvedCurriculum:
     title: str
     description: str
     modules: list[ResolvedModule] = field(default_factory=list)
+    # Image assets referenced from any text block's markdown, deduped by
+    # content hash. Carried out-of-band — the generator copies these into
+    # ``static/`` and they are stripped before curriculum.json is written
+    # (the SvelteKit frontend never sees them).
+    assets: list[Asset] = field(default_factory=list)
 
 
 def resolve_curriculum(
@@ -105,6 +111,10 @@ def resolve_curriculum(
         visualization_provider = D3foundryStub()
 
     resolved_modules: list[ResolvedModule] = []
+    # Image assets are deduped globally on `dest_relative` (which is keyed
+    # on the content hash), so a single image referenced from N lessons is
+    # copied exactly once into the generated project.
+    assets_by_dest: dict[str, Asset] = {}
     for module in curriculum.curriculum.modules:
         resolved_modules.append(
             _resolve_module(
@@ -113,6 +123,7 @@ def resolve_curriculum(
                 quiz_provider,
                 exercise_provider,
                 visualization_provider,
+                assets_by_dest,
             )
         )
 
@@ -121,6 +132,7 @@ def resolve_curriculum(
         title=curriculum.curriculum.title,
         description=curriculum.curriculum.description,
         modules=resolved_modules,
+        assets=list(assets_by_dest.values()),
     )
 
 
@@ -130,6 +142,7 @@ def _resolve_module(
     quiz_provider: QuizProvider,
     exercise_provider: ExerciseProvider,
     visualization_provider: VisualizationProvider,
+    assets_by_dest: dict[str, Asset],
 ) -> ResolvedModule:
     pre = None
     post = None
@@ -158,6 +171,7 @@ def _resolve_module(
                 quiz_provider,
                 exercise_provider,
                 visualization_provider,
+                assets_by_dest,
             )
         )
 
@@ -178,6 +192,7 @@ def _resolve_lesson(
     quiz_provider: QuizProvider,
     exercise_provider: ExerciseProvider,
     visualization_provider: VisualizationProvider,
+    assets_by_dest: dict[str, Asset],
 ) -> ResolvedLesson:
     resolved_blocks: list[ResolvedContentBlock] = []
     for idx, block in enumerate(lesson.content_blocks):
@@ -190,6 +205,7 @@ def _resolve_lesson(
                 exercise_provider,
                 visualization_provider,
                 location,
+                assets_by_dest,
             )
         )
     return ResolvedLesson(
@@ -206,10 +222,11 @@ def _resolve_block(
     exercise_provider: ExerciseProvider,
     visualization_provider: VisualizationProvider,
     location: str,
+    assets_by_dest: dict[str, Asset],
 ) -> ResolvedContentBlock:
     try:
         if isinstance(block, TextBlock):
-            return _resolve_text(block, base_dir, location)
+            return _resolve_text(block, base_dir, location, assets_by_dest)
         if isinstance(block, VideoBlock):
             return _resolve_video(block, location)
         if isinstance(block, QuizBlock):
@@ -245,7 +262,10 @@ def _resolve_block(
 
 
 def _resolve_text(
-    block: TextBlock, base_dir: Path, location: str
+    block: TextBlock,
+    base_dir: Path,
+    location: str,
+    assets_by_dest: dict[str, Asset],
 ) -> ResolvedContentBlock:
     content_path = base_dir / block.ref
     try:
@@ -258,11 +278,25 @@ def _resolve_text(
     if not text.strip():
         logger.warning("%s: markdown file `%s` is empty.", location, content_path)
 
+    # Scan for image refs, copy-relative on disk, rewrite to absolute
+    # `/content/<hash>/<basename>` URLs that work at any SvelteKit route.
+    # Missing images surface as ContentResolutionError tagged with the
+    # block location for parity with other resolution errors.
+    try:
+        rewritten, lesson_assets = resolve_markdown_assets(text, content_path)
+    except ContentResolutionError as exc:
+        raise ContentResolutionError(f"{location}: {exc}") from exc
+
+    for asset in lesson_assets:
+        # Dedup globally — two lessons referencing the same image hash to
+        # the same dest_relative, so the dict swallows the duplicate.
+        assets_by_dest.setdefault(asset.dest_relative, asset)
+
     return ResolvedContentBlock(
         type="text",
         source=None,
         ref=block.ref,
-        content={"markdown": text, "path": str(content_path)},
+        content={"markdown": rewritten, "path": str(content_path)},
     )