@pretextbook/web-editor 0.12.0 → 0.14.0

package/dist/sectionUtils.d.ts

@@ -151,7 +151,7 @@ export declare function updateLatexDivisionMetadata(division: Division, changes:
  * Returns `null` when the conversion fails, so callers can disable the convert
  * action / fall back.
  */
-export declare function latexDivisionToTaggedPretext(division: Pick<Division, "content" | "type" | "xmlId" | "title">): string | null;
+export declare function latexDivisionToTaggedPretext(division: Pick<Division, "source" | "type" | "xmlId" | "title">): string | null;
 /** Create a new blank LaTeX section as a `Division`. */
 export declare function createNewLatexSection(title?: string): DocumentSection;
 /** Create a blank LaTeX introduction. */
@@ -217,7 +217,7 @@ export declare function extractDivisionMetadata(content: string): {
  * Pass `null` for `xmlId` or `label` to remove the attribute entirely.
  * Omit a key (or pass `undefined`) to leave it unchanged.
  *
- * Returns a new `DocumentSection` with updated `content`, `title`, and `type`.
+ * Returns a new `DocumentSection` with updated `source`, `title`, and `type`.
  */
 export declare function updateSectionMetadata(section: DocumentSection, changes: {
     title?: string;
@@ -248,6 +248,7 @@ export declare function parseMarkdownFrontmatter(content: string): {
     type: DivisionType;
     xmlId: string;
     label: string;
+    title: string;
     body: string;
 } | null;
 /** Build a `---`-fenced frontmatter block for a markdown division. */
@@ -255,15 +256,23 @@ export declare function buildMarkdownFrontmatter(meta: {
     type: DivisionType;
     xmlId: string;
     label: string;
+    title?: string;
 }): string;
-/** Extract a markdown division's leading `# heading` text, or `null` if none. */
+/**
+ * Extract a markdown division's leading `# heading` text, or `null` if none.
+ * Legacy fallback only — titles now live in frontmatter's `title` key; see
+ * {@link extractMarkdownDivisionMetadata}. Kept so documents saved before the
+ * frontmatter-title migration still show a real title instead of "Untitled".
+ */
 export declare function deriveMarkdownTitle(body: string): string | null;
 /**
  * Derive a markdown division's title, type, `xml:id`, and `label` directly from
- * its source — the frontmatter for the structural metadata and the leading
- * `# heading` for the title.  Markdown analogue of {@link extractDivisionMetadata};
- * returns `null` when the frontmatter is absent/malformed (both common
- * mid-edit), so callers can skip the update rather than clobber metadata.
+ * its source — all from the frontmatter block. Markdown analogue of
+ * {@link extractDivisionMetadata}; returns `null` when the frontmatter is
+ * absent/malformed (both common mid-edit), so callers can skip the update
+ * rather than clobber metadata. When the frontmatter carries no `title` (a
+ * document predating the migration to a frontmatter title), falls back to the
+ * body's leading `# heading`.
  */
 export declare function extractMarkdownDivisionMetadata(content: string): {
     title: string;
@@ -273,12 +282,12 @@ export declare function extractMarkdownDivisionMetadata(content: string): {
 } | null;
 /**
  * Update the title, type (`division`), `xml:id`, and `label` of a markdown
- * division.  Structural metadata is rewritten in the frontmatter block; a title
- * change rewrites the body's leading `# heading`.  Markdown analogue of
- * {@link updateSectionMetadata} (which is XML-only and would wrongly inject a
- * `<title>` element).  Pass `null`/empty for `label` to clear it; omit a key to
- * leave it unchanged.  The `xml:id` is never cleared — it is the division's
- * identity — so an empty value falls back to the record's existing id.
+ * division — all rewritten in the frontmatter block; the body is left
+ * untouched. Markdown analogue of {@link updateSectionMetadata} (which is
+ * XML-only and would wrongly inject a `<title>` element). Pass `null`/empty
+ * for `label` to clear it; omit a key to leave it unchanged. The `xml:id` is
+ * never cleared — it is the division's identity — so an empty value falls
+ * back to the record's existing id.
  */
 export declare function updateMarkdownDivisionMetadata(division: Division, changes: {
     title?: string;
@@ -306,8 +315,12 @@ export declare function canEmbedDivisionRefs(sourceFormat: SourceFormat): boolea
  *
  * Only direct children are returned — the function does not recurse.
  * Call it for each division in the pool to build the full tree.
+ *
+ * `sourceFormat` is the parent division's format: only that format's include
+ * syntax is scanned, and its verbatim spans are blanked first, so example
+ * placeholders in code samples don't become phantom children.
  */
-export declare function parseDivisionRefs(content: string): string[];
+export declare function parseDivisionRefs(content: string, sourceFormat: SourceFormat): string[];
 /**
  * Like {@link parseDivisionRefs} but also returns the division type inferred
  * from the tag name (e.g. `<plus:chapter ref="x"/>` → `{ type: "chapter", xmlId: "x" }`).
@@ -318,7 +331,7 @@ export declare function parseDivisionRefs(content: string): string[];
  * skipped. The generic `<plus:division ref="x"/>` alias falls back to type
  * `"section"`, matching {@link tagToType}'s default for unrecognised tags.
  */
-export declare function parseDivisionRefsWithTypes(content: string): {
+export declare function parseDivisionRefsWithTypes(content: string, sourceFormat: SourceFormat): {
     xmlId: string;
     type: DivisionType;
 }[];
@@ -340,7 +353,7 @@ export interface AssetRef {
  * disjoint tag set (`image`/`doenet`) so the two kinds of include are never
  * conflated.
  */
-export declare function parseAssetRefs(content: string): AssetRef[];
+export declare function parseAssetRefs(content: string, sourceFormat: SourceFormat): AssetRef[];
 /**
  * Rewrite every asset placeholder for `oldRef` in `content` to use `newRef`
  * instead, leaving any other attributes (e.g. `width="50%"`) untouched. The

package/dist/types/editor.d.ts

@@ -6,8 +6,8 @@ export type AssetKind = "image" | "doenet";
 export interface Asset {
     /** Stable server-assigned identifier (hidden from users). */
     id: string;
-    /** Human-readable display name shown in the library UI. */
-    name: string;
+    /** Human-readable display title shown in the library UI. */
+    title: string;
     /** Short reference used when authoring references, e.g. `"euler-painting"`.
      * Authors write e.g. `<plus:image ref="euler-painting"/>` and the build system
      * resolves it to the necessary core PreTeXt markup based upon the kind of
@@ -26,28 +26,29 @@ export interface Asset {
     /**
      * Whether this asset is backed by an uploaded/fetched file rather than
      * being defined purely by `source`. File-based image assets emit a
-     * `source` attribute on the generated `<image>` element (from
-     * {@link fileRef}, falling back to {@link url}); non-file image assets
-     * carry no `source` attribute and rely entirely on their authored
+     * `source` attribute on the generated `<image>` element built from this
+     * asset's {@link ref} plus a file extension (e.g. `ref="euler-painting"`
+     * with a PNG upload emits `source="euler-painting.png"`); non-file image
+     * assets carry no `source` attribute and rely entirely on their authored
      * `source` content.
      */
     isFile?: boolean;
     /**
-     * Publicly accessible URL used **only** as the asset-manager thumbnail
-     * (`<img src={url}>`). It is no longer the value written to the `<image>`
-     * `source` attribute — use {@link fileRef} for that. It remains the
-     * `source` fallback when `fileRef` is absent, for backwards compatibility.
+     * Publicly accessible URL used as the asset-manager thumbnail
+     * (`<img src={url}>`). Its filename extension (if any) is also used, as a
+     * fallback after {@link fileRef}, to determine the extension appended to
+     * `ref` for the generated `<image source="...">` attribute. The URL itself
+     * (e.g. a UUID-based storage key) is never written into the document.
      */
     url?: string;
     /**
-     * The exact string emitted as the `source` attribute of the generated
-     * `<image>` element for a file-backed asset — typically a bare external
-     * filename like `"euler-painting.png"`. The PreTeXt build server treats
-     * `<image source="X">` as an external-asset filename and prepends
-     * `external/` itself, so this must be a bare filename, not a URL.
+     * The server-assigned storage filename for a file-backed asset (e.g. a
+     * UUID-based key). Its extension, if present, is used to build the
+     * `source` attribute of the generated `<image>` element as
+     * `"{ref}.{extension}"` — the rest of this value (e.g. the UUID itself)
+     * is never written into the document.
      *
-     * Only meaningful when {@link isFile} is true. When absent, the emit sites
-     * fall back to {@link url} so existing hosts keep working unchanged.
+     * Only meaningful when {@link isFile} is true.
      */
     fileRef?: string;
     /** Mime type for the asset, if applicable.  Used for hints only. */
@@ -76,7 +77,7 @@ export interface FeedbackSubmission {
 }
 /**
  * Represents the full content state of the editor at any point in time.
- * When `sourceFormat` is `"pretext"`, `pretextSource` mirrors `sourceContent`.
+ * When `sourceFormat` is `"pretext"`, `pretextSource` mirrors `source`.
  * When `sourceFormat` is `"latex"`, `pretextSource` holds the result of
  * converting the LaTeX source, or `pretextError` holds a description of why
  * conversion failed.
@@ -86,11 +87,11 @@ export interface FeedbackSubmission {
  */
 export interface EditorContentState {
     /** The raw source string as typed/loaded by the user. */
-    sourceContent: string;
-    /** The format of `sourceContent`. */
+    source: string;
+    /** The format of `source`. */
     sourceFormat: SourceFormat;
     /**
-     * The PreTeXt XML derived from `sourceContent`.
+     * The PreTeXt XML derived from `source`.
      * Present when conversion succeeded (or when the source is already PreTeXt).
      */
     pretextSource?: string;

package/dist/types/sections.d.ts

@@ -4,7 +4,7 @@ import type { SourceFormat } from "./editor";
  * section, worksheet, etc. — is a `Division`.  Divisions are stored as a flat
  * pool of records on the host (Rails) side; hierarchy is expressed by
  * embedding `<plus:division ref="xml-id"/>` placeholder tags inside a parent
- * division's `content`.
+ * division's `source`.
  *
  * Type-specific aliases (`<plus:chapter ref="..."/>`, `<plus:section ref="..."/>`)
  * are accepted by the editor as equivalent to `<plus:division ref="..."/>`.
@@ -59,7 +59,7 @@ export interface Division {
      * child refs as `::section{ref="child-id"}` leaf directives, and LaTeX as
      * `\plus{section}{child-id}` macros.
      */
-    content: string;
+    source: string;
 }
 /**
  * @deprecated Use `DivisionType` instead.  This alias will be removed in a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretextbook/web-editor",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "private": false,
   "description": "A web-based editor for PreTeXt documents, with simple preview functionality",
   "keywords": [
@@ -51,8 +51,8 @@
     "@monaco-editor/react": "^4.8.0-rc.3",
     "@pretextbook/completions": "^0.0.3",
     "@pretextbook/format": "^0.2.0",
-    "@pretextbook/latex-pretext": "^0.0.11",
-    "@pretextbook/remark-pretext": "^0.0.9",
+    "@pretextbook/latex-pretext": "^0.0.12",
+    "@pretextbook/remark-pretext": "^0.0.10",
     "@pretextbook/visual-editor": "^0.0.6",
     "@tailwindcss/vite": "^4.1.18",
     "constrained-editor-plugin": "^1.4.0",