Merge branch 'main' into manifest-tasks

Author: crandmck

README.md

@@ -2,8 +2,38 @@
 
 [![Netlify Status](https://api.netlify.com/api/v1/badges/c2fe0e49-4596-48e8-8e1a-9cf62d56bca2/deploy-status)](https://app.netlify.com/sites/contentauth/deploys)
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator, and deployed
-on [Netlify](https://www.netlify.com/).
+## Overview
+
+This repo contains the source code and content to generate the <https://opensource.contentauthenticity.org/> website.  This site is built using [Docusaurus 2](https://docusaurus.io/), a modern static site generator, and deployed on [Netlify](https://www.netlify.com/).
+
+### Directory structure
+
+The `docs` sub-directory contains documentation content (in markdown or `.mdx` format) in the following sub-directories:
+- [`js-sdk/api`](./docs/js-sdk/api): [API documentation](https://opensource.contentauthenticity.org/docs/js-sdk/api/) for the JavaScript library generated from the source code; see [Generating JavaScript API docs](#generating-javascript-sdk-api-docs).
+- [`js-sdk`](./docs/js-sdk/): [Other documentation](https://opensource.contentauthenticity.org/docs/js-sdk/getting-started/overview) for the JavaScript library.
+(./scripts/generate-api-docs/index.js)
+- `includes`: Markdown content imported (transcluded) into other files.
+- `manifest`: Content for the [Understanding manifests](https://opensource.contentauthenticity.org/docs/manifest/understanding-manifest) section.
+- `static`: Additional assets such as images.
+
+Additionally, the [scripts/fetch-readme.js](./scripts/fetch-readme.js) script dynamically downloads documentation files (sometimes just the `README.md` but often other markdown files, too) from other repos in the SDK. See [Running the fetch script](#running-fetch-script).
+
+This table summarizes the content that this script fetches from other repos.
+
+| Sub-directory | Content fetched from... | Description | 
+|-----------|-------------------------|-------------|
+| `c2pa-c` | [c2pa-c](https://github.com/contentauth/c2pa-c) | C library docs. |
+| `c2pa-min` | [c2pa-min](https://github.com/contentauth/c2pa-min) | Minimal Rust example app. |
+| `c2pa-node` | [c2pa-node](https://github.com/contentauth/c2pa-node) | Node library docs. |
+| `c2pa-node-example`  | [c2pa-node-example](https://github.com/contentauth/c2pa-node-example) | Node example app.|
+| `c2pa-python` | [c2pa-python](https://github.com/contentauth/c2pa-python) | Python library docs. |
+| `c2pa-python example` | [c2pa-python-example](https://github.com/contentauth/c2pa-python-example) | Python example app. |
+| `c2pa-service-example` | [c2patool-service-example](https://github.com/contentauth/c2patool-service-example) | C2PA Tool service example app. |
+| `c2patool` | [c2pa-rs cli directory](https://github.com/contentauth/c2pa-rs/cli) | C2PA Tool docs. |
+| `js-sdk` | [c2pa-js](https://github.com/contentauth/c2pa-js) | JavaScript library docs. |
+| `rust-sdk` | [c2pa-rs](https://github.com/contentauth/c2pa-rs) | Rust library docs. |
+
+The [Manifest store reference](https://opensource.contentauthenticity.org/docs/manifest/manifest-ref) is an HTML file generated by the  [json-manifest-reference](https://github.com/contentauth/json-manifest-reference) repository and imported manually.
 
 ## Installation
 
@@ -16,7 +46,7 @@ $ npm install
 
 ## Local development
 
-**Prerequisite**: To build the site locally, you must first check out the JavaScript library in a sibling directory and build the API docs there.  In the parent directory of `opensource.contentauth.org`, enter these commands:
+**Prerequisite**: To build the site locally, you must first check out the JavaScript library in a sibling directory and build the API docs there.  In the parent directory of the `opensource.contentauth.org` directory, enter these commands:
 
 ```
 $ git clone [email protected]:contentauth/c2pa-js.git
@@ -34,23 +64,23 @@ This command starts a local development server and opens up a browser window. Mo
 
 ### Running fetch script
 
-The `/scripts/fetch-readme.js` script pulls markdown files from other repos (e.g. `c2patool`). To rerun this script for local build, enter this command:
+The `/scripts/fetch-readme.js` script pulls markdown files from other repos (e.g. `c2pa-rs`). To rerun this script for local build, enter this command:
 
 ```
 npm run docs:fetch-readme
 ```
 
-NOTE: If you added a **new** repo to get .md files from, then you need to manually add the directory, add a `.gitkeep` file to it, and then commit it to Git.
+NOTE: If you need to get markdown files from a **new** repo that you added, then you need to manually add the sub-directory, add a `.gitkeep` file to it, and then commit it to this repository.
 
-### Generate JavaScript SDK API docs
+### Generating JavaScript SDK API docs
 
-The `/scripts/generate-api-docs/index.js` script generates API docs for the JS SDK. To run this script for local build, enter this command:
+The `/scripts/generate-api-docs/index.js` script generates API docs for the JS SDK (assuming you've checked it out in a sibling directory). To run this script for local build, enter this command:
 
 ```
 npm run docs:generate-api-docs
 ```
 
-## Build
+### Building
 
 ```
 $ npm run build
@@ -60,8 +90,7 @@ This command generates static content into the `build` directory and can be serv
 
 ### Deployment
 
-Deployments are handled automatically by Netlify. Please open up a pull request with any changes and a preview site
-should be created automatically so that the preview can be shared before merging.
+Deployments are handled automatically by Netlify. Please open up a pull request with any changes and a preview site will be created automatically so you can share what the rendered site will look like before merging.
 
 ### Forcing a site rebuild
 

docs/js-sdk/examples/.gitkeep

@@ -25,8 +25,7 @@ The JavaScript library uses several modern browser technologies, including:
 
 The JavaScript library is a monorepo containing the following packages intended for client use:
 
-- [**c2pa**](https://opensource.contentauthenticity.org/docs/js-sdk/api/c2pa) is the main package used for loading and verifying manifests. This package runs all of the processing
-  logic on the client using a [WebAssembly](https://webassembly.org/) module and exposes a [TypeScript](https://www.typescriptlang.org/)-compatible API for easy integration.
+- [**c2pa**](https://opensource.contentauthenticity.org/docs/js-sdk/api/c2pa) is the main package used for loading and verifying manifests. This package runs all of the processing logic on the client using a [WebAssembly](https://webassembly.org/) module and exposes a [TypeScript](https://www.typescriptlang.org/)-compatible API for easy integration.
 - **c2pa-wc** provides UI components designed with input from the C2PA UX working group. It enables users to get up and running with standard UI patterns quickly and easily in any front-end environment.
 - **@contentauth/react** provides a hooks interface for React components to quickly get manifest and thumbnail data in your React app.
 
@@ -59,7 +58,7 @@ Because of these requirements, **the library is not supported on any version of
 ![CAI JavaScript library browser support](../../../static/img/caniuse.png)
 
 :::info
-This chart is accurate as of June, 2024. For the most up-to-date browser support information, see [caniuse.com](https://caniuse.com/wasm,webworkers,cryptography,typedarrays,fetch).
+This chart is accurate as of December, 2024. For the most up-to-date browser support information, see [caniuse.com](https://caniuse.com/wasm,webworkers,cryptography,typedarrays,fetch).
 :::
 
 ## Debugging
@@ -72,7 +71,7 @@ To view debug messages in the console, use your browser's inspector, go to the C
 localStorage.debug = 'c2pa:*';
 ```
 
-The debuging information includes millisecond timing differences so you can get an idea of how long different events take.
+The debugging information includes millisecond timing differences so you can get an idea of how long different events take.
 
 :::note
 Debug calls and statements are stripped out of minified production builds to reduce file size.

docs/js-sdk/examples/quickstart/.gitkeep

@@ -5,7 +5,6 @@ title: Quick start
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
-import Sandbox from '../../../src/components/Sandbox';
 
 ## Prerequisites
 
@@ -37,19 +36,17 @@ The quickest way to get up and running is to use a CDN such as [jsDelivr](https:
 Static assets include the following, as seen in the config passed to [`createC2pa`](../../js-sdk/api/c2pa.createc2pa):
 
 ```js
+const version = '0.24.2';
 {
   wasmSrc: `https://cdn.jsdelivr.net/npm/c2pa@${version}/dist/assets/wasm/toolkit_bg.wasm`,
   workerSrc: `https://cdn.jsdelivr.net/npm/c2pa@${version}/dist/c2pa.worker.min.js`,
 }
 ```
 
 :::caution
-The version numbers provided in the CDN URLs _must_ match in all of the places you reference the
-library. To make it easy, use a variable that provides the version as shown in the example.
+The version numbers provided in the CDN URLs _must_ be the same in all of the places you reference the library. To make it easy, use a variable that provides the version as shown in the example.
 :::
 
-<Sandbox file="/examples/cdn/main.ts" displayType="preview" />
-
 ### Using a package manager
 
 You can also bring in the library with a package manager, such as `npm`, `pnpm`, or `yarn`. This way, all of the client side code is hosted with your app and there are no external dependencies. For example, using `npm`:
@@ -71,24 +68,30 @@ Be sure to configure your server to send proper `Content-Type` headers for these
 
 Examples for common build systems are shown below. They are also available in the [c2pa-js-examples repository](https://github.com/contentauth/c2pa-js-examples).
 
-export const ExampleLink = ({ example }) => {
-  const linkText = `examples/${example}`;
-  const link = `https://github.com/contentauth/c2pa-js/tree/main/${linkText}`;
-  return (
-    <div className="example-link">
-      An example project is available here: <a href={link}>{linkText}</a>
-    </div>
-  );
-};
+import CodeBlock from '@theme/CodeBlock';
+import ViteExample from '!!raw-loader!../examples/quickstart/vite-main.ts';
+import RollupExample from '!!raw-loader!../examples/quickstart/rollup-main.ts';
+import WebPackExample from '!!raw-loader!../examples/quickstart/webpack-main.ts';
 
 <Tabs lazy>
-  <TabItem value="vite" label="Vite" default>
-    <Sandbox file="/examples/quick-start/main.ts" />
-  </TabItem>
-  <TabItem value="rollup" label="Rollup">
-    <Sandbox example="minimal-ts-rollup" file="/src/main.ts" browserPath="/" />
-  </TabItem>
-  <TabItem value="webpack" label="Webpack">
-    <Sandbox example="minimal-ts-webpack" file="/src/main.ts" browserPath="/" />
-  </TabItem>
+<TabItem value="vite" label="Vite" default>
+
+This example is from [c2pa-js-examples/minimal-ts-vite/](https://github.com/contentauth/c2pa-js-examples/blob/main/minimal-ts-vite/). To view and execute this example in a live [code sandbox](https://codesandbox.io/docs/learn/legacy-sandboxes/overview), see [Code Sandbox: Vite example](../guides/sandbox-qs-vite.mdx).
+
+<CodeBlock language="ts">{ViteExample}</CodeBlock>
+</TabItem>
+
+<TabItem value="rollup" label="Rollup">
+
+This example is from [c2pa-js-examples/minimal-ts-rollup/](https://github.com/contentauth/c2pa-js-examples/blob/main/minimal-ts-rollup/). To view and execute this example in a live [code sandbox](https://codesandbox.io/docs/learn/legacy-sandboxes/overview), see [Code Sandbox: Rollup example](../guides/sandbox-qs-rollup.mdx).
+
+<CodeBlock language="ts">{RollupExample}</CodeBlock>
+</TabItem>
+
+<TabItem value="webpack" label="Webpack">
+
+This example is from [c2pa-js-examples/minimal-ts-webpack/](https://github.com/contentauth/c2pa-js-examples/blob/main/minimal-ts-webpack/). To view and execute this example in a live [code sandbox](https://codesandbox.io/docs/learn/legacy-sandboxes/overview), see [Code Sandbox: Webpack example](../guides/sandbox-qs-webpack.mdx).
+
+<CodeBlock language="ts">{WebPackExample}</CodeBlock>
+</TabItem>
 </Tabs>

docs/js-sdk/examples/view-manifest/.gitkeep

@@ -42,7 +42,7 @@ examples of configuring popular build systems, see the [Quick start guide](../ge
 
 To host the library yourself, expose the static asset files with the following response headers to avoid errors with some browsers:
 
-- `c2pa/dist/assets/wasm/toolkit_bg.wasm`: Serve with `Content-Type: application/wasm` reponse header.
+- `c2pa/dist/assets/wasm/toolkit_bg.wasm`: Serve with `Content-Type: application/wasm` response header.
 - `c2pa/dist/c2pa.worker.min.js`: Serve with `Content-Type: text/javascript` response header.
 
 Then pass these URLs to the `createC2pa` function; for example:

docs/js-sdk/getting-started/overview.mdx

@@ -0,0 +1,11 @@
+---
+id: sandbox-rollup
+title: 'Code Sandbox: Rollup example'
+hide_table_of_contents: true
+---
+
+import Sandbox from '../../../src/components/Sandbox';
+
+The source code for this example is in the [c2pa-js-examples repo](https://github.com/contentauth/c2pa-js-examples/tree/main/minimal-ts-rollup).
+
+<Sandbox file="../examples/quickstart/rollup-main.ts" browserPath="/" />

docs/js-sdk/getting-started/quick-start.mdx

@@ -0,0 +1,11 @@
+---
+id: sandbox-vite
+title: 'Code Sandbox: Vite example'
+hide_table_of_contents: true
+---
+
+import Sandbox from '../../../src/components/Sandbox';
+
+The source code for this example is in the [c2pa-js-examples repo](https://github.com/contentauth/c2pa-js-examples/blob/main/minimal-ts-vite/).
+
+<Sandbox file="../examples/quickstart/vite-main.ts" browserPath="/" />

docs/js-sdk/guides/hosting.mdx

@@ -0,0 +1,11 @@
+---
+id: sandbox-webpack
+title: 'Code Sandbox: Webpack example'
+hide_table_of_contents: true
+---
+
+import Sandbox from '../../../src/components/Sandbox';
+
+The source code for this example is in the [c2pa-js-examples repo](https://github.com/contentauth/c2pa-js-examples/tree/main/minimal-ts-webpack).
+
+<Sandbox file="../examples/quickstart/webpack-main.ts" browserPath="/" />